# OfficeCLI Raw XML Access vs Typed Operations: Why Level 3 Is Insufficient for Level 2 Tasks > Discover why OfficeCLI Level 3 raw XML access is insufficient for Level 2 tasks. Learn how Level 2 typed operations ensure safety and validation for efficient development. - Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI) - Tags: internals - Published: 2026-08-06 --- **OfficeCLI provides two distinct abstraction layers where Level 2 typed operations offer built-in safety and validation, while Level 3 raw XML access serves only as an escape hatch for edge cases that the semantic model cannot express.** OfficeCLI, maintained in the **iOfficeAI/OfficeCLI** repository, is an open-source command-line interface for manipulating Office documents. While it exposes both high-level typed verbs and low-level raw XML access, relying on Level 3 operations for standard document editing tasks introduces significant risks compared to the validated, automated workflows available at Level 2. ## Understanding OfficeCLI's Abstraction Layers OfficeCLI implements a dual-layer architecture for document manipulation: - **Level 2 – Typed Operations**: Works with a semantic model of the document (paragraphs, tables, shapes). The CLI parses the OpenXML package, validates requests against the schema, and emits minimal XML changes. Common verbs include `set`, `add`, `remove`, `move`, `swap`, and `batch`. - **Level 3 – Raw XML Access**: Bypasses the semantic layer to provide direct read/write access to underlying XML parts. The CLI streams raw part bytes, allows unrestricted editing, and defers validation until session shutdown. Verbs include `raw` and `raw-set`. According to the source code in [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs) (line 1133), the raw XML command pipeline handles the `raw-set` verb by streaming part bytes directly, while the typed operation pipeline performs pre-validation before any bytes reach the document package. ## Why Raw XML Access (Level 3) Is Insufficient for Level 2 Tasks Using Level 3 operations for tasks that Level 2 can handle introduces three critical deficiencies: **Safety Mechanisms** Level 2 commands perform schema validation **before** applying changes, preventing malformed XML from ever reaching the document. In contrast, `raw-set` operations in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) defer validation until the end of the session, meaning a single malformed element can corrupt the file and trigger a full-package rollback. **Granularity and Automation** Typed verbs target high-level elements (e.g., `/body/p[2]`, `/slide[1]/shape[3]`) and automatically handle ID generation, namespace fixes, and related part updates. When using raw XML access, you must manually create unique IDs, update relationships, and preserve part ordering—tasks that [`WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs) (line 107) handles automatically for typed operations but require manual intervention at Level 3. **Performance Characteristics** Bulk Level 2 operations are batched and de-duplicated by the CLI's internal optimizer. Raw `raw-set` operations on individual elements create separate serialization passes, resulting in quadratic performance degradation as the number of changes increases. The implementation in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) processes typed operations as atomic batches while treating each `raw-set` call as an independent stream operation. ## Source Code Implementation The distinction between these layers is hard-coded in the OfficeCLI architecture: | File | Purpose | Key Implementation Detail | |------|---------|---------------------------| | [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs) | Raw XML pipeline | Line 1133 implements the `raw-set` verb handling that streams raw bytes and triggers final validation | | [`src/officecli/Handlers/WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/WordHandler.cs) | Word-specific fallbacks | Line 107 contains fallback logic for raw XML when typed walkers cannot see specific constructs like VML markup | | [`src/officecli/Help/SchemaHelpRenderer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Help/SchemaHelpRenderer.cs) | Help system bridge | Line 10 demonstrates the transition between typed help rendering and raw JSON output | | [`sdk/python/officecli.py`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/python/officecli.py) | Python SDK wrapper | Line 212 exposes the raw verb set to Python scripts | | [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js) | Node.js SDK wrapper | Line 158 mirrors the raw XML API for JavaScript consumers | ## Practical Code Examples ### Level 2 Typed Operation: Update Paragraph Text The following command uses the semantic model to safely update text while handling all namespace and relationship management automatically: ```bash officecli set report.docx /body/p[2] --prop text="Quarterly results are up 12 %" ``` ### Level 3 Raw XML: Insert Custom VML Shape When the typed model does not expose specific markup (such as custom VML), you must use raw access: ```bash # Extract the raw XML part officecli raw report.docx /word/document.xml > document.xml # Append custom VML markup cat <<'EOF' >> document.xml EOF # Push the modified XML back into the package officecli raw-set report.docx /word/document.xml --data @document.xml ``` ### Handling Undocumented Attributes For attributes not supported by the typed schema (e.g., `w:customAttr` on table cells), Level 3 is necessary but requires external XML tools: ```bash officecli raw report.docx /word/document.xml | \ xmlstarlet ed -u "//w:tc[w:tcPr][1]/w:tcPr/@w:customAttr" -v "foo" > edited.xml officecli raw-set report.docx /word/document.xml --data @edited.xml ``` ### Mixing Levels in Batch Operations You can combine both approaches in a single session, though the CLI processes them sequentially: ```bash officecli batch report.docx <<'EOF' set /body/p[1] --prop bold=true raw-set /word/document.xml --data @custom.xml add /slide[2] --type shape --prop "type=rect;fill=red" EOF ``` The CLI executes typed `set` and `add` commands first, applies the `raw-set`, then validates the entire document package. ## When to Use Level 3 Raw Access vs Level 2 Typed Operations **Choose Level 2 typed operations** when performing standard document edits: text modifications, style changes, table manipulation, or shape insertion. The semantic layer in [`WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs) and related handlers provides schema validation, automatic ID generation, and relationship management. **Reserve Level 3 raw access** exclusively for edge cases: custom VML markup, undocumented attributes, proprietary extensions, or when you must preserve exact byte-for-byte part content that the typed model would normalize. As implemented in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs), raw access should be treated as an escape hatch rather than a primary interface. ## Summary - **Level 2 typed operations** provide pre-validation, automatic ID handling, and batched performance optimization for standard document editing tasks. - **Level 3 raw XML access** (`raw` and `raw-set` verbs) defers validation to session end, requires manual management of XML IDs and relationships, and scales poorly for bulk operations. - The OfficeCLI source code explicitly separates these concerns in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) and [`WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs), exposing Level 3 only for constructs that the semantic model cannot yet express. - Mixing both levels in batch operations is supported, but each `raw-set` incurs independent serialization overhead compared to batched typed commands. ## Frequently Asked Questions ### What is the difference between Level 2 and Level 3 in OfficeCLI? Level 2 provides a typed, semantic interface to Office documents where commands like `set` and `add` manipulate high-level objects (paragraphs, tables) with automatic schema validation. Level 3 exposes raw XML parts through `raw` and `raw-set` verbs, allowing direct byte-level manipulation of OpenXML but requiring manual handling of IDs, namespaces, and relationships. ### When should I use raw XML access instead of typed operations? Use raw XML access only when the Level 2 semantic model cannot express your required change, such as inserting custom VML markup, setting undocumented attributes, or preserving specific XML formatting that typed operations would normalize. According to the source in [`WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs), any construct visible to the typed walkers should be manipulated through Level 2 verbs for safety. ### Can I mix Level 2 and Level 3 commands in the same OfficeCLI session? Yes. You can combine typed operations and raw XML access in batch files or sequential commands. The CLI processes typed commands first, then applies raw modifications, and finally runs the validation pass defined in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) before closing the document package. ### Does raw XML access skip validation entirely in OfficeCLI? No, but it defers validation. While Level 2 validates changes before applying them, Level 3 operations stream raw bytes immediately and validate the entire package only at session shutdown. This means Level 3 errors can corrupt the document mid-session, whereas Level 2 errors are caught before any file modification occurs.