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

> Validate Word, PowerPoint, and Excel files against OpenXML schema using the OfficeCLI validate command. Get JSON output and CI-friendly exit codes.

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

---

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

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

```bash
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.cs) and wraps them via `OutputFormatter.WrapEnvelope`:

```bash
officecli validate --json report.docx

```

Example output:

```json
{
  "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:

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

```

## CI Pipeline Integration

The **exit code semantics** (line 60 in [`CommandBuilder.Check.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Check.cs)) make the **OfficeCLI validate command** ideal for automated gates:

```bash
#!/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Check.cs) | Defines the **validate** command, registers the `<file>` argument, `--json` option, and orchestrates execution |
| [`src/officecli/Handlers/DocumentHandlerFactory.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/DocumentHandlerFactory.cs) | Opens documents and dispatches to the correct format handler |
| [`src/officecli/Handlers/Word/WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Word/WordHandler.cs) | Implements `Validate()` for Word documents using the Open XML SDK |
| [`src/officecli/CommandBuilder.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.cs) | Contains `FormatValidationErrors()` for JSON serialization |
| [`src/officecli/OutputFormatter.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/OutputFormatter.cs) | Provides `WrapEnvelope()` for uniform CLI response structure |
| [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Check.cs) (lines 12–20), [`WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs), and [`OutputFormatter.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/DocumentHandlerFactory.cs) resolves the appropriate handler based on file extension, with format-specific validation logic in dedicated handler classes like [`WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.