How to Validate Documents Against OpenXML Schema Using the OfficeCLI Validate Command

Run officecli validate <filepath> to check any Word (.docx), PowerPoint (.pptx), or Excel (.xlsx) file for Open XML schema compliance, with optional --json output and exit codes for CI integration.

The OfficeCLI validate command provides a fast, scriptable way to verify that Office documents conform to the Open XML specification. Whether you're gating a CI pipeline or debugging document corruption, this built-in verb executes a full schema validation pass and reports structural errors with precise location details.

How the OfficeCLI Validate Command Works

The validate verb is implemented as a first-class command in the OfficeCLI source. When you invoke it, the tool chains together several components from the codebase:

• Command parsing → CommandBuilder.Check.cs
• Document resolution → DocumentHandlerFactory
• Schema validation → Format-specific handlers (e.g., WordHandler.Validate())
• Result formatting → FormatValidationErrors and OutputFormatter

This architecture lets the same CLI interface handle multiple Office formats through a unified pipeline.

Running Basic Validation

The simplest invocation checks a single document and prints human-readable results:

officecli validate report.docx

Output on success:

Validation passed: no errors found.

Output on failure:

Found 3 validation error(s):
  [InvalidTag] Unexpected element <w:tbl> in paragraph structure
  [MissingRequired] Required child <w:p> missing from body
  ...

The command exits with code 0 for valid documents and 1 when errors are detected. This supports straightforward shell conditionals:

officecli validate contract.docx && echo "Ready for production"

JSON Output for Automation

Add --json for machine-parseable results. This serializes errors through FormatValidationErrors in CommandBuilder.cs and wraps them via OutputFormatter.WrapEnvelope:

officecli validate --json report.docx

Example output:

{
  "success": false,
  "data": {
    "count": 2,
    "errors": [
      {
        "type": "InvalidTag",
        "description": "Unexpected element <w:tbl>",
        "path": "word/document.xml#/w:body[1]/w:p[3]"
      },
      {
        "type": "MissingRequired",
        "description": "Required child <w:p> missing",
        "part": "word/document.xml"
      }
    ]
  }
}

Pipe this to tools like jq for selective extraction:

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

CI Pipeline Integration

The exit code semantics (line 60 in CommandBuilder.Check.cs) make the OfficeCLI validate command ideal for automated gates:

#!/bin/bash
if officecli validate --json build-output.docx > validation.json; then
  echo "Schema validation passed"
else
  echo "Schema errors detected:"
  jq '.data.errors | length' validation.json
  exit 1
fi

Separate streams support clean logging: validation errors write to stderr (lines 47–57), while structured JSON goes to stdout.

Internal Architecture

Understanding the source helps troubleshoot edge cases. The validation pipeline flows through these key files:

File	Purpose
src/officecli/CommandBuilder.Check.cs	Defines the validate command, registers the <file> argument, --json option, and orchestrates execution
src/officecli/Handlers/DocumentHandlerFactory.cs	Opens documents and dispatches to the correct format handler
src/officecli/Handlers/Word/WordHandler.cs	Implements Validate() for Word documents using the Open XML SDK
src/officecli/CommandBuilder.cs	Contains FormatValidationErrors() for JSON serialization
src/officecli/OutputFormatter.cs	Provides WrapEnvelope() for uniform CLI response structure
src/officecli/ResidentServer.cs	Routes validation requests to a resident server when available (lines 22–27), avoiding document re-open overhead

The Open XML SDK validator performs the actual schema checking. Each handler's Validate() method walks the document parts, collects ValidationError objects, and returns them for formatting.

Resident Mode Performance

When a resident server is already handling the target file, the command forwards the validation request there instead of re-opening the document. This optimization, handled in ResidentServer.cs, significantly speeds repeated operations on the same file.

Summary

• Run officecli validate <file> for quick manual checks with human-readable output
• Add --json for structured results suitable for scripts and CI systems
• Check exit codes: 0 = valid, 1 = errors found—standard semantics for pipeline gating
• Leverage resident mode for faster repeated validations on open documents
• Reference source locations: CommandBuilder.Check.cs (lines 12–20), WordHandler.cs, and OutputFormatter.cs implement the core logic

Frequently Asked Questions

What file formats does the OfficeCLI validate command support?

The OfficeCLI validate command supports all Open XML-based formats: Word documents (.docx), PowerPoint presentations (.pptx), and Excel workbooks (.xlsx). The DocumentHandlerFactory.cs resolves the appropriate handler based on file extension, with format-specific validation logic in dedicated handler classes like WordHandler.cs.

How do I capture validation errors without the full JSON envelope?

The --json flag always wraps results via OutputFormatter.WrapEnvelope. To extract just the error array, pipe through jq: officecli validate --json file.docx | jq '.data.errors'. For raw stderr capture of human-readable errors, omit --json and redirect stderr to a file: officecli validate file.docx 2> errors.txt.

Can I validate multiple files in one command?

Currently, the validate command accepts a single <file> argument. For batch validation, use shell loops: for f in *.docx; do officecli validate --json "$f" || echo "FAIL: $f"; done. Each invocation maintains independent exit codes for granular failure detection.

Why does validation fail on documents that open fine in Office?

Microsoft Office applies repair heuristics when loading documents, silently fixing many schema violations. The OfficeCLI validate command reports the underlying structural issues that Office tolerates. A document passing validation guarantees standards-compliant Open XML; one with errors may still function in Office but risks interoperability problems with strict parsers.

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