# OfficeCLI JSON Output Schema: How Command Responses Are Structured

> Understand the OfficeCLI JSON output schema. Learn how command responses are consistently structured for DOCX, XLSX, and PPTX files using top-level fields like format, element, and properties when the --json flag is active.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: api-reference
- Published: 2026-07-13

---

**OfficeCLI formats every command result as JSON when the `--json` flag is used, following a versioned master schema that defines consistent top-level fields including `format`, `element`, `operations`, `paths`, `properties`, and `children` across all DOCX, XLSX, and PPTX document types.**

The iOfficeAI/OfficeCLI repository provides a command-line interface for manipulating Office documents, and when you append the `--json` flag to any command, the tool emits structured data rather than human-readable text. Understanding the JSON output schema is essential for building automation scripts, CI/CD pipelines, or integrations that programmatically parse workbook metadata, paragraph styles, or presentation elements.

## The Master Schema Contract

All OfficeCLI JSON responses adhere to a single, versioned master schema located at [`schemas/help/_schema.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/_schema.json). This file serves as the contract that every element-specific schema must follow, describing the top-level fields and validation rules for properties, types, and allowed values.

The master schema defines the structural contract for six core fields that appear in every response:

- `format` – The document type (docx, xlsx, or pptx)
- `element` – The specific Office element being queried or modified
- `operations` – Supported CRUD operations (add, set, get, query, remove)
- `paths` – Positional and stable path patterns accepted by the CLI
- `properties` – The actual data payload containing element-specific values
- `children` – Descriptors for nested elements and their cardinality

## Element-Specific Schemas by Document Type

For each supported document type, OfficeCLI maintains dedicated schema files that extend the master schema and enumerate concrete properties. These files live in format-specific subdirectories under `schemas/help/`.

### XLSX Workbook Schema

The [`schemas/help/xlsx/workbook.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/xlsx/workbook.json) file defines metadata properties for Excel files, including author, title, calculation mode, and date1904 settings. It also declares the `sheet` element as a valid child with cardinality constraints.

### DOCX Paragraph Schema

The [`schemas/help/docx/paragraph.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/docx/paragraph.json) file specifies paragraph styling attributes such as alignment, indentation, spacing, and text runs. It defines the `run` element as a child that can appear zero or more times within a paragraph.

### PPTX Table Schema

The [`schemas/help/pptx/table.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/pptx/table.json) file describes table layout properties including cell fills, row counts, column counts, and cell-specific attributes. It supports operations on individual cells within slide tables.

## Standard JSON Response Structure

When serialized by the core formatter, every JSON response conforms to this consistent structure derived from [`_schema.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/_schema.json):

```json
{
  "format": "docx|xlsx|pptx",
  "element": "<element-name>",
  "operations": {
    "add": true|false,
    "set": true|false,
    "get": true|false,
    "query": true|false,
    "remove": true|false
  },
  "paths": {
    "positional": ["/<path-segment>..."],
    "stable": ["/<stable-path>..."]
  },
  "properties": {
    "<prop-name>": "<value>"
  },
  "children": [
    {
      "element": "<child-element>",
      "pathSegment": "<segment>",
      "cardinality": "0..n|1..n|1|0..1",
      "key": "<key-attr>",
      "keyValues": [ "val1", "val2" ]
    }
  ]
}

```

The `properties` object contains only the values requested by the command, while the `operations` object indicates which actions are valid for the specific element type.

## Runtime Schema Processing

The CLI implements a two-stage pipeline for schema handling that ensures type-safe JSON generation.

### Schema Loading

The [`src/officecli/Help/SchemaHelpLoader.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Help/SchemaHelpLoader.cs) class locates and parses JSON schema files at program startup, caching the master schema and all element-specific definitions. This loader validates that requested elements have corresponding schema files before command execution.

### Output Formatting

The [`src/officecli/Core/OutputFormatter.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/OutputFormatter.cs) class queries the appropriate schema based on document type and element name, extracts the requested properties from the Office document model, and serializes the result into the standard JSON structure. This component ensures that all emitted JSON strictly conforms to the schema contract defined in [`_schema.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/_schema.json).

## Practical Command Examples

### Querying XLSX Workbook Metadata

To retrieve workbook-level properties with the JSON output schema:

```bash
officecli xlsx get workbook --json

```

**Sample output:**

```json
{
  "format": "xlsx",
  "element": "workbook",
  "operations": { "add": false, "set": true, "get": true, "query": true, "remove": false },
  "paths": { "positional": ["/"] },
  "properties": {
    "author": "Alice",
    "title": "Q1 Report",
    "calc.mode": "manual",
    "workbook.date1904": false,
    "revisionNumber": "3"
  },
  "children": [
    { "element": "sheet", "pathSegment": "{SheetName}", "cardinality": "1..n" }
  ]
}

```

### Setting DOCX Paragraph Properties

When modifying paragraph alignment:

```bash
officecli docx set paragraph /body/p[2] --prop alignment=center --json

```

**Sample output:**

```json
{
  "format": "docx",
  "element": "paragraph",
  "operations": { "add": false, "set": true, "get": true, "query": false, "remove": false },
  "paths": { "positional": ["/body/p[N]"] },
  "properties": {
    "alignment": "center"
  },
  "children": [
    { "element": "run", "pathSegment": "r[N]", "cardinality": "0..n" }
  ]
}

```

### Adding PPTX Table Cells

To add a cell to a presentation table:

```bash
officecli pptx add cell /slide[1]/table[0]/row[1] --prop text="Hello" --json

```

**Sample output:**

```json
{
  "format": "pptx",
  "element": "cell",
  "operations": { "add": true, "set": true, "get": true, "query": false, "remove": true },
  "paths": { "positional": ["/slide[N]/table[K]/row[R]/cell[C]"] },
  "properties": {
    "text": "Hello"
  }
}

```

### Querying DOCX Shapes

To query all shapes in a Word document:

```bash
officecli docx query shape --json

```

**Sample output:**

```json
{
  "format": "docx",
  "element": "shape",
  "operations": { "add": false, "set": true, "get": true, "query": true, "remove": false },
  "paths": { "positional": ["/body/drawings/drawing[N]/shape[S]"] },
  "properties": {
    "type": "picture",
    "description": "Company logo"
  },
  "children": []
}

```

## Summary

- **OfficeCLI JSON output schema** is governed by [`schemas/help/_schema.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/_schema.json), which mandates six top-level fields for every response.
- **Element-specific schemas** extend the master contract for DOCX, XLSX, and PPTX elements, defining concrete properties and valid child elements in files like [`workbook.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/workbook.json), [`paragraph.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/paragraph.json), and [`table.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/table.json).
- **Runtime components** [`SchemaHelpLoader.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SchemaHelpLoader.cs) and [`OutputFormatter.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/OutputFormatter.cs) handle schema parsing and JSON serialization, ensuring all `--json` outputs conform to the versioned contract.
- **Consistent structure** across commands enables reliable parsing by automation tools, with the `operations` field indicating available CRUD actions and `paths` providing stable addressing patterns.

## Frequently Asked Questions

### What fields are guaranteed in every OfficeCLI JSON response?

Every JSON response includes six mandatory fields defined in the master schema: `format` (document type), `element` (target entity), `operations` (supported CRUD flags), `paths` (addressing patterns), `properties` (data payload), and `children` (nested element descriptors). These fields appear even when empty, ensuring predictable parsing by downstream tools.

### How does OfficeCLI determine which schema to use for validation?

The [`SchemaHelpLoader.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SchemaHelpLoader.cs) class in `src/officecli/Help/` maps the combination of document format (docx/xlsx/pptx) and element name to a specific JSON file under `schemas/help/`. For example, a command targeting an XLSX workbook loads [`schemas/help/xlsx/workbook.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/xlsx/workbook.json), while the master schema in [`schemas/help/_schema.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/_schema.json) provides the structural contract that all element schemas must satisfy.

### Can I rely on the JSON schema stability across OfficeCLI versions?

Yes, the schema is versioned and designed for machine readability. The master schema defines strict typing and cardinality rules, and [`OutputFormatter.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/OutputFormatter.cs) ensures that all emitted JSON conforms to these contracts. However, you should pin your integration to specific OfficeCLI releases, as new properties may be added to element schemas in future versions while maintaining backward compatibility for existing fields.

### Where does the actual JSON serialization happen in the codebase?

The [`OutputFormatter.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/OutputFormatter.cs) file in `src/officecli/Core/` contains the serialization logic. It queries the loaded schema definitions, extracts the requested properties from the Office document object model, and constructs the JSON object according to the standard structure. This class is invoked by the command handlers orchestrated in [`src/officecli/CommandBuilder.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.cs) whenever the `--json` flag is present.