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

> Learn to use the OfficeCLI validate command for OpenXML schema validation on Word, Excel, and PowerPoint files. Ensure document compliance with exit codes and optional JSON output for CI.

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

---

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

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

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

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

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

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

```

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

```bash

# 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Check.cs), [`DocumentHandlerFactory.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/DocumentHandlerFactory.cs), and format-specific handlers like [`WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs) within the `Validate()` method, which invokes the Open XML SDK validator. The command orchestration and error formatting occur in [`CommandBuilder.Check.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Check.cs) and [`CommandBuilder.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.cs), while [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) handles performance optimizations for repeated validations.