# How OfficeCLI Round-Trip Dump Serializes Documents into Replayable Batch JSON

> Learn how OfficeCLI's round-trip dump serializes documents into replayable batch JSON for byte-for-byte reconstruction. Understand low-level edit operations.

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

---

**OfficeCLI's `dump` command exports Office documents as batch JSON containing low-level edit operations that can be piped back through the `batch` command to reconstruct the original file byte-for-byte.**

The round-trip dump feature in iOfficeAI/OfficeCLI provides a deterministic, lossless serialization mechanism for Word, PowerPoint, and Excel documents. By traversing a document's OpenXML structure and emitting a linear sequence of operations, OfficeCLI creates a replayable JSON payload that serves as both an archive and a transport format for document manipulation.

## Understanding the Batch JSON Format

The **batch JSON** schema defines a list of edit operations: `add`, `set`, `replace`, and `delete`. When dumping a document, OfficeCLI generates `raw-set` or `replace` operations that capture:

- **Verbatim XML fragments** (e.g., `<w:tbl>` table elements, paragraph structures)
- **Data-URI encoded binary blobs** (OLE objects, embedded images, fonts, ActiveX controls)

This granular approach ensures every component of the source file is preserved. The `WordHandler` explicitly identifies these elements as "dump→batch round-trip carriers" for complex document parts.

## Three-Stage Serialization Process

### Stage 1: Command Parsing and Validation

The `dump` sub-command is processed in [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs). The command validates that `--format` is set to `batch` — any other format triggers an error:

```csharp
// ResidentServer.cs lines 1975-1979
if (format != "batch")
{
    throw new ArgumentException("Dump format must be 'batch'");
}

```

This strict enforcement ensures output compatibility with the `batch` command's input requirements.

### Stage 2: Document Traversal and Operation Generation

The `WordHandler` (and equivalent PowerPoint/Excel handlers) walks each OpenXML part in the source document. For every structural element, it emits operations containing either raw XML or base64-encoded binary data.

In [`src/officecli/Handlers/WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/WordHandler.cs), this logic handles:

- **OLE objects** (lines 504-527): Embedded spreadsheets, equations, and legacy content
- **ActiveX controls** (lines 655-657): Form controls and scripted elements
- **Charts, fonts, and media**: All binary relationships in the OpenXML package

The handler preserves exact document state by capturing complete XML subtrees and binary attachments as data URIs.

### Stage 3: JSON Emission and Output

The generated operations are serialized to JSON with a wrapper containing:

- `operations`: The linear operation list
- `success`: Boolean completion status
- `warnings`: Any non-fatal issues during traversal

The output structure in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) (lines 846-852) ensures self-contained, parseable results suitable for piping or file storage.

## Round-Trip Execution Examples

### Command-Line Usage

```bash

# Serialize DOCX to batch JSON

officecli dump report.docx --format batch > report.dump.json

# Replay to recreate original document

cat report.dump.json | officecli batch --input - > recreated.docx

```

### Node SDK Programmatic Access

```javascript
const { dump } = require('@officecli/sdk');

(async () => {
  // Generate batch JSON from document
  const batch = await dump('report.docx', { format: 'batch' });
  
  // `batch` is a JSON string suitable for storage or transmission
  fs.writeFileSync('report.dump.json', batch);
  
  // Later: replay through batch command or SDK
  const recreated = await batchFromJSON(batch, 'recreated.docx');
})();

```

## Key Implementation Files

| File | Purpose |
|------|---------|
| [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs) | Command parsing, format validation, JSON streaming |
| [`src/officecli/Handlers/WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/WordHandler.cs) | Core traversal logic, operation generation for Word documents |
| [`src/officecli/Help/SchemaHelpFlatRenderer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Help/SchemaHelpFlatRenderer.cs) | Schema documentation and validation definitions |
| [`sdk/node/index.d.ts`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.d.ts) | TypeScript definitions for SDK `dump` method |

## Summary

- **Round-trip dump** serializes Office documents as batch JSON through three stages: command validation, document traversal, and JSON emission.
- The `WordHandler` and related handlers capture **verbatim XML** and **data-URI binary blobs** to ensure lossless serialization.
- Output conforms to the **batch command schema**, enabling immediate replay via pipe or SDK.
- Implementation spans [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) for orchestration and handler classes for format-specific traversal.

## Frequently Asked Questions

### What makes the dump format "replayable"?

The batch JSON uses the **same schema** consumed by the `batch` command. Each `raw-set` or `replace` operation in the dump corresponds to a valid batch instruction, so piping the output directly into `officecli batch --input -` reconstructs the original document without transformation.

### Does round-trip dump preserve binary content like images and OLE objects?

Yes. The `WordHandler` specifically encodes binary elements — images, fonts, OLE objects, and ActiveX controls — as **data URIs within the JSON**. The source code comments (lines 504-527, 655-657) identify these as critical "round-trip carriers" that maintain document fidelity.

### Can I use round-trip dump without the command-line interface?

Yes. The **Node SDK** exposes a `dump` method with identical behavior. As defined in [`sdk/node/index.d.ts`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.d.ts), this method accepts a file path and format option, returning the same JSON structure available through the CLI.

### What happens if I specify a format other than "batch"?

The [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) parser (lines 1975-1979) **rejects non-batch formats** with an `ArgumentException`. This design choice enforces output compatibility with the replay pipeline and prevents accidental generation of unsupported serialization formats.