iofficeai--officecli/schemas/help/docx/header.json

{
  "$schema": "../_schema.json",
  "format": "docx",
  "element": "header",
  "parent": "/",
  "addParent": "/",
  "operations": {
    "add": true,
    "set": true,
    "get": true,
    "query": true,
    "remove": true
  },
  "paths": {
    "positional": [
      "/header[N]"
    ]
  },
  "note": "Headers are stored in HeaderParts and referenced by the last sectPr. Duplicate type rejected at Add. 'first' type auto-enables TitlePage. Field insertion uses complex fldChar (begin/instr/separate/result/end). A single Add supports at most one text + one field pair; composite headers like 'Page X of Y' must be built in steps by adding additional runs/fields to the header's paragraph (/header[N]/p[1]) after creation — see examples.",
  "examples": [
    "Simple page-number header: officecli add file.docx / --type header --prop field=page --prop align=right",
    "'Page X of Y' — build in steps after creating the header:",
    "  1) officecli add file.docx / --type header --prop text=\"Page \" --prop align=right",
    "  2) officecli add file.docx \"/header[1]/p[1]\" --type field --prop fieldType=page",
    "  3) officecli add file.docx \"/header[1]/p[1]\" --type run --prop text=\" of \"",
    "  4) officecli add file.docx \"/header[1]/p[1]\" --type field --prop fieldType=numpages"
  ],
  "properties": {
    "type": {
      "type": "enum",
      "description": "header scope.",
      "values": [
        "default",
        "first",
        "even"
      ],
      "aliases": [
        "kind",
        "ref"
      ],
      "add": true,
      "set": true,
      "get": true,
      "examples": [
        "--prop type=default"
      ],
      "readback": "innerText of HeaderFooterValues",
      "enforcement": "strict"
    },
    "text": {
      "type": "string",
      "description": "header text (single run).",
      "add": true,
      "set": true,
      "get": true,
      "examples": [
        "--prop text=\"My Header\""
      ],
      "readback": "concatenated Text.Descendants",
      "enforcement": "strict"
    },
    "align": {
      "type": "enum",
      "values": [
        "left",
        "center",
        "right",
        "justify",
        "both",
        "distribute"
      ],
      "aliases": [
        "alignment"
      ],
      "add": true,
      "set": true,
      "get": true,
      "examples": [
        "--prop align=center"
      ],
      "readback": "first-paragraph Justification.Val.InnerText",
      "enforcement": "strict"
    },
    "direction": {
      "type": "enum",
      "values": [
        "rtl",
        "ltr"
      ],
      "aliases": [
        "dir",
        "bidi"
      ],
      "description": "Reading direction. 'rtl' writes <w:bidi/> on the header paragraph, <w:rtl/> on the paragraph mark, and <w:rtl/> on every run (text + field runs alike) so Arabic / Hebrew character order reverses end-to-end. 'ltr' clears all three.",
      "add": true,
      "set": true,
      "get": false,
      "examples": [
        "--prop direction=rtl"
      ],
      "enforcement": "strict"
    },
    "font": {
      "type": "string",
      "add": true,
      "set": true,
      "get": true,
      "examples": [
        "--prop font=\"Arial\""
      ],
      "readback": "Ascii or HighAnsi font name",
      "enforcement": "strict"
    },
    "size": {
      "type": "font-size",
      "description": "font size. Accepts bare number or pt-suffixed.",
      "add": true,
      "set": true,
      "get": true,
      "examples": [
        "--prop size=12"
      ],
      "readback": "unit-qualified pt (e.g. \"12pt\")",
      "enforcement": "strict"
    },
    "bold": {
      "type": "bool",
      "add": true,
      "set": true,
      "get": true,
      "examples": [
        "--prop bold=true"
      ],
      "readback": "true when bold, key absent otherwise",
      "enforcement": "strict"
    },
    "italic": {
      "type": "bool",
      "add": true,
      "set": true,
      "get": true,
      "examples": [
        "--prop italic=true"
      ],
      "readback": "true when italic, key absent otherwise",
      "enforcement": "strict"
    },
    "color": {
      "type": "color",
      "description": "font color. Accepts #RRGGBB, RRGGBB, named colors (red, blue…), rgb(r,g,b), or 3-char shorthand (F00).",
      "add": true,
      "set": true,
      "get": true,
      "examples": [
        "--prop color=#FF0000"
      ],
      "readback": "#-prefixed uppercase hex",
      "enforcement": "strict"
    },
    "field": {
      "type": "enum",
      "description": "complex field to insert (page/numpages/date/author/title/time/filename, or an arbitrary field name).",
      "values": [
        "page",
        "pagenum",
        "pagenumber",
        "numpages",
        "date",
        "author",
        "title",
        "time",
        "filename"
      ],
      "add": true,
      "set": false,
      "get": false,
      "examples": [
        "--prop field=page"
      ],
      "readback": "not surfaced as a distinct key",
      "enforcement": "strict"
    }
  }
}