How to Use the OfficeCLI Validate Command to Check Documents Against OpenXML Schema

The officecli validate command performs OpenXML schema validation on Word, Excel, and PowerPoint documents, returning exit code 0 for compliant files and exit code 1 for schema violations, with optional JSON output for CI integration.

The iOfficeAI/OfficeCLI repository provides a first-class command-line interface for Office document manipulation, including robust verification of structural integrity against OpenXML standards. Using the OfficeCLI validate command, developers can automate schema compliance checks in build pipelines, ensuring that generated .docx, .xlsx, or .pptx files adhere to the strict Open XML specification before deployment.

Basic Syntax and Usage

The validation workflow starts with a simple invocation targeting any supported Office format:

officecli validate <path-to-file>

By default, the command produces human-readable output to stdout. To capture machine-readable results for scripting, append the global --json flag:

officecli validate --json report.docx

The Validation Pipeline Architecture

When you execute officecli validate, the tool runs a six-stage pipeline orchestrated across several specialized handlers in the repository.

Command Construction and Argument Parsing

In src/officecli/CommandBuilder.Check.cs (lines 12-20), the validate verb registers a required <file> argument and the global --json option. This builder constructs the command action that drives the validation logic and establishes the contract for exit code semantics.

Resident Mode Shortcut

If a resident server is already handling the file, the request forwards through ResidentServer.cs (lines 22-27) to avoid re-opening the document. This optimization ensures that long-running server instances can process validation requests without the overhead of repeated assembly loading.

Document Handler Resolution

The DocumentHandlerFactory.Open method inside src/officecli/Handlers/DocumentHandlerFactory.cs inspects the file extension and instantiates the correct format-specific handler—WordHandler, PowerPointHandler, or ExcelHandler. This factory pattern isolates format-specific logic while presenting a uniform validation interface.

Schema Validation Execution

For Word documents, the concrete implementation resides in src/officecli/Handlers/Word/WordHandler.cs within the Validate() method. This method walks the Open XML parts, invokes the Open XML SDK's validator, and collects ValidationError objects describing any structural deviations from the schema. Each error includes metadata such as the problematic tag, expected children, and the specific document part (e.g., word/document.xml).

Result Formatting and Output

The command supports two output modes:

• Human-readable: Prints a friendly success message or writes each validation error to stderr (lines 47-57 in the command builder), allowing CI systems to separate diagnostic output from standard logs.
• JSON envelope: When --json is supplied, FormatValidationErrors (defined in src/officecli/CommandBuilder.cs, lines 18-34) serializes the error list. The method wraps the payload using OutputFormatter.WrapEnvelope to include a success boolean and uniform CLI metadata.

Exit Code Semantics

The command returns exit code 0 when validation passes and exit code 1 when any schema errors are detected (line 60). This binary signaling makes the tool ideal for gatekeeping automated workflows:

officecli validate contract.docx && echo "Schema compliant" || echo "Validation failed"

Practical Examples for CI/CD Integration

Validate a document and check the exit code in a shell script:

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

Pipe JSON output to jq for filtering specific error types:

officecli validate --json presentation.pptx | jq '.errors[] | {type: .type, path: .path}'

Integrate into a CI pipeline to prevent merging non-compliant documents:

# In your CI configuration (e.g., .github/workflows/validate.yml)

- name: Validate Office Documents
  run: |
    for file in docs/*.docx; do
      officecli validate "$file" || exit 1
    done

Summary

• The OfficeCLI validate command provides first-class OpenXML schema validation for Word, Excel, and PowerPoint documents via a single CLI invocation.
• The validation pipeline spans CommandBuilder.Check.cs, DocumentHandlerFactory.cs, and format-specific handlers like WordHandler.cs.
• Exit code 0 indicates schema compliance, while exit code 1 signals validation failures, enabling simple shell-based automation.
• The --json flag produces structured output via FormatValidationErrors and OutputFormatter.WrapEnvelope, essential for programmatic error processing.
• Resident server mode optimizes performance by avoiding redundant document loading across multiple validation calls.

Frequently Asked Questions

What file formats does the OfficeCLI validate command support?

The command supports all standard Office Open XML formats, including Word (.docx), Excel (.xlsx), and PowerPoint (.pptx). The DocumentHandlerFactory.cs resolves the appropriate handler based on file extension, ensuring each format receives specialized validation logic while maintaining a consistent CLI interface.

How do I capture validation errors in JSON format for CI pipelines?

Append the --json global option to your command: officecli validate --json document.docx. This triggers FormatValidationErrors in CommandBuilder.cs to serialize the error list, which OutputFormatter.WrapEnvelope then wraps in a standardized envelope containing the error count, details array, and success boolean. You can pipe this output directly to tools like jq or parse it in Python scripts for automated reporting.

What does exit code 1 indicate when running officecli validate?

Exit code 1 indicates that the OpenXML validator detected one or more schema violations in the document. According to the implementation in CommandBuilder.Check.cs (line 60), any presence of ValidationError objects causes the command to return 1, while a clean document returns 0. This semantics allows shell scripts to use the command directly in conditional statements without parsing output text.

Where is the core validation logic implemented in the OfficeCLI source code?

The schema validation implementation resides in format-specific handlers under src/officecli/Handlers/. For Word documents, the logic lives in WordHandler.cs within the Validate() method, which invokes the Open XML SDK validator. The command orchestration and error formatting occur in CommandBuilder.Check.cs and CommandBuilder.cs, while ResidentServer.cs handles performance optimizations for repeated validations.

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