OfficeCLI JSON Output Schemas for Get, Query, and Error Responses

OfficeCLI returns structured JSON arrays for successful get and query operations and enveloped error objects for failures, with schemas defined in the schemas/help/ directory and formatting logic implemented in OutputFormatter.cs.

When using the --json flag with the iOfficeAI/OfficeCLI tool, the command-line interface serializes results into predictable schemas. These OfficeCLI JSON output schemas ensure that automation scripts can reliably parse document elements from Word, Excel, and PowerPoint files, as well as handle failure states programmatically.

Get and Query Response Schema

Successful get and query commands return a JSON array (or single object) of document nodes. Each node follows a generic structure defined in the repository's schema files under schemas/help/.

Generic Node Structure

Every returned node includes base fields:

• type: String identifier (e.g., "shape", "cell", "picture")
• path: OOXML selector path that identified the node

Element-specific properties extend this base structure according to format-specific schema files.

Format-Specific Schema Files

The exact properties for each element type are defined in individual JSON schema files:

• Word shapes: schemas/help/docx/shape.json defines properties like id, name, fill, and text
• Excel cells: schemas/help/xlsx/cell.json specifies cell-specific attributes
• PowerPoint pictures: schemas/help/pptx/picture.json outlines picture element properties

These schemas extend the base node structure defined in schemas/help/_schema.json.

Error Response Schema

When commands fail, OfficeCLI returns an enveloped error object produced by OutputFormatter.WrapErrorEnvelope. Unlike text-mode errors, JSON errors write the envelope to stdout with an empty stderr.

The error envelope structure:

{
  "error": {
    "code": 1,
    "message": "Error: Path not found: nonexistent[foo]"
  }
}

• code: Non-zero integer exit code
• message: Human-readable error description

Implementation Details

The JSON serialization logic resides in two key locations according to the iOfficeAI/OfficeCLI source code.

src/officecli/Core/OutputFormatter.cs implements the MakeResponse and WrapErrorEnvelope methods that construct the final JSON output for both success and error cases.

src/officecli/ResidentServer.cs serves as the central hub where the final JSON response is assembled and written to the client.

Practical Examples

Successful Get Operation

officecli get mydoc.docx /body/shape[3] --json

Output:

[
  {
    "type": "shape",
    "path": "/body/shape[3]",
    "id": "2",
    "name": "MyShape",
    "fill": "FF0000",
    "text": "Hello"
  }
]

Failed Query Operation

officecli query mydoc.docx "nonexistent[foo]" --json

Output:

{
  "error": {
    "code": 1,
    "message": "Error: Path not found: nonexistent[foo]"
  }
}

Summary

• OfficeCLI JSON output schemas are defined in the schemas/help/ directory, with base node structure specified in _schema.json
• Get and query responses return arrays of nodes containing type and path fields plus format-specific properties from files like docx/shape.json or xlsx/cell.json
• Error responses use an enveloped structure with error.code and error.message fields generated by WrapErrorEnvelope in OutputFormatter.cs
• All JSON output is finalized in ResidentServer.cs within the iOfficeAI/OfficeCLI codebase

Frequently Asked Questions

What fields are included in every OfficeCLI JSON response?

Every successful get or query response includes type and path fields in each node. The type field identifies the element category (e.g., "shape", "cell"), while the path field contains the OOXML selector path used to locate the element.

How does OfficeCLI handle JSON output for failed commands?

Failed commands return a structured error envelope to stdout (not stderr) containing an error object with code and message properties. This envelope is generated by the WrapErrorEnvelope method in OutputFormatter.cs, ensuring consistent error handling for automation scripts.

Where are the JSON schemas for specific Office document elements defined?

Format-specific schemas are located in the schemas/help/ directory. For example, Word shape properties are defined in schemas/help/docx/shape.json, Excel cells in schemas/help/xlsx/cell.json, and PowerPoint pictures in schemas/help/pptx/picture.json.

What is the difference between get and query JSON outputs?

Both get and query commands use identical JSON schemas. The get command retrieves specific elements by exact path, while query searches using selectors, but both return arrays of document nodes following the same format-specific schemas in the schemas/help/ directory.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}