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

> Master OpenXML schema validation with OfficeCLI. Run officecli validate to check documents, receiving a 0 exit code for success or 1 for failure.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: how-to-guide
- Published: 2026-08-03

---

**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**:

```bash
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`

```bash
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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:

```bash
officecli validate --json presentation.pptx

```

Example failure response:

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

```

The JSON envelope mechanism in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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

```powershell
$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:

```bash
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) success path |
| `1` | Schema validation errors detected (`validateFailure`) | [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) error counting |
| `2` | Unsupported features (e.g., LaTeX markers) | [`McpServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs)** – Core request processing, `_lastValidateErrorCount` tracking, exit code determination, and JSON envelope generation with `forceFailure` logic.
- **[`src/officecli/McpServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/McpServer.cs)** – High-level command documentation describing the "delivery gate" pattern and validation prerequisites.
- **[`src/officecli/CommandBuilder.Check.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs), with command registration in [`CommandBuilder.Check.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Check.cs) and documentation in [`McpServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.