How to Use the `validate` Command for OpenXML Schema Validation in OfficeCLI

Run officecli validate <file> to perform a read-only schema check on any OpenXML document, returning exit code 0 for success or 1 for validation failures.

The validate command is a core read-only operation in the OfficeCLI toolkit that verifies whether Word, Excel, or PowerPoint documents conform to the official OpenXML schema. This guide explains how the validation logic works internally, how to interpret its output formats, and how to integrate it into CI/CD pipelines using the source code from the iOfficeAI/OfficeCLI repository.

Basic Syntax and Usage

The simplest invocation checks a single document and reports schema errors to stderr:

officecli validate my-document.docx

Output behavior follows Unix conventions:

• Success: No output, exit code 0
• Failure: Error details written to stderr, exit code 1

officecli validate report.docx
echo $?  # → 0 if valid, 1 if schema errors detected

How Validation Works Internally

The validation pipeline in src/officecli/ResidentServer.cs processes validate requests through four distinct stages:

1. Command dispatch – The resident server receives the request and detects the verb via request.Command.Equals("validate", StringComparison.OrdinalIgnoreCase)【ResidentServer.cs†L824-L830】.

2. Error collection – The underlying OpenXML SDK performs schema validation; OfficeCLI tallies violations in the _lastValidateErrorCount field.

3. Exit code mapping – After validation completes, errors trigger exit code 1 (validateFailure), aligning with CI-friendly semantics documented in src/officecli/McpServer.cs【McpServer.cs†L525-L531】.

4. Output formatting – Results stream to stderr in plain text, or to stdout as structured JSON when --json is specified.

Crucially, validation is purely read-only—the source file is never modified, ensuring failed checks cannot corrupt documents.

JSON Output for Automation

Add --json to receive machine-parseable results wrapped in a standard envelope:

officecli validate --json presentation.pptx

Example failure response:

{
  "success": false,
  "warnings": [
    {
      "message": "Element <w:p> is missing required attribute …",
      "severity": "Error"
    }
  ]
}

The JSON envelope mechanism in ResidentServer.cs forces success: false when validation fails (forceFailure)【ResidentServer.cs†L71-L78】, and the final process exit code mirrors this boolean—0 for success, 1 for failure【ResidentServer.cs†L79-L84】.

Integrating with Scripts and CI Pipelines

PowerShell Validation Gate

$exit = & officecli validate --json contract.docx | ConvertFrom-Json
if ($LASTEXITCODE -ne 0) {
    Write-Error "Schema validation failed with $($exit.warnings.Count) errors"
    exit 1
}

Batch Processing with Validation

The validate verb combines with other operations in batch mode, acting as a delivery gate:

officecli batch --json my-doc.docx \
    "add /slide[1] --type shape --prop text=Hello" \
    "validate"

If the final validate step detects schema errors, the entire batch aborts with exit code 1.

Exit Code Semantics

Code	Meaning	Source Location
0	Clean validation, document conforms to OpenXML schema	ResidentServer.cs success path
1	Schema validation errors detected (validateFailure)	ResidentServer.cs error counting
2	Unsupported features (e.g., LaTeX markers)	McpServer.cs delivery gate documentation

These semantics specifically support delivery gate workflows where validation must pass before documents proceed to downstream systems.

Key Source Files

• src/officecli/ResidentServer.cs – Core request processing, _lastValidateErrorCount tracking, exit code determination, and JSON envelope generation with forceFailure logic.
• src/officecli/McpServer.cs – High-level command documentation describing the "delivery gate" pattern and validation prerequisites.
• src/officecli/CommandBuilder.Check.cs – Command-line parser that registers the validate verb and --json flag support.

Summary

• officecli validate performs read-only OpenXML schema validation without modifying source files.
• Exit codes (0/1/2) integrate directly with CI pipelines and shell scripts.
• Text mode sends errors to stderr; JSON mode (--json) provides structured output for programmatic consumption.
• The validation logic resides in ResidentServer.cs, with command registration in CommandBuilder.Check.cs and documentation in McpServer.cs.

Frequently Asked Questions

What types of documents can the validate command check?

The validate command accepts any OpenXML format: .docx (Word), .xlsx (Excel), .pptx (PowerPoint), and their macro-enabled variants. The underlying OpenXML SDK performs schema validation regardless of document type.

Does validation modify my document if errors are found?

No. The validate command is explicitly read-only. As implemented in ResidentServer.cs, no write operation occurs—errors are tallied and reported without persisting any changes to disk.

How do I fail a CI build when validation detects schema errors?

Use the exit code directly: officecli validate document.docx || exit 1. For structured logging, capture JSON output with --json and parse the success boolean or $LASTEXITCODE in PowerShell to gate subsequent pipeline stages.

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