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

{
  "$schema": "../_schema.json",
  "format": "docx",
  "element": "hyperlink",
  "elementAliases": ["link"],
  "parent": "paragraph",
  "operations": {
    "add": true,
    "set": true,
    "get": true,
    "query": true,
    "remove": true
  },
  "paths": {
    "positional": [
      "/body/p[N]/hyperlink[M]"
    ]
  },
  "note": "Aliases: link. Exactly one of 'url' (external) or 'anchor' (internal bookmark ref) is required. Colors default to theme Hyperlink (or 0563C1 fallback) with single underline.",
  "extends": "_shared/hyperlink",
  "properties": {
    "url": {
      "type": "string",
      "description": "external URL. Aliases: href, link. docx Set accepts all three (url canonical).",
      "aliases": [
        "href",
        "link"
      ],
      "add": true,
      "set": true,
      "get": true,
      "examples": [
        "--prop url=https://example.com"
      ],
      "readback": "URL string",
      "enforcement": "report"
    },
    "anchor": {
      "type": "string",
      "description": "bookmark name for internal links. Set after Add not supported — formatting lives on inner runs (Set the run, not the hyperlink wrapper).",
      "aliases": [
        "bookmark"
      ],
      "add": true,
      "set": false,
      "get": true,
      "examples": [
        "--prop anchor=section1"
      ],
      "readback": "anchor name for internal links",
      "enforcement": "report"
    },
    "tooltip": {
      "type": "string",
      "description": "hover text (w:tooltip / ScreenTip) shown when the cursor rests on the link. Set after Add not supported — supply on Add. Renders as the HTML title attribute in the preview.",
      "add": true,
      "set": false,
      "get": true,
      "examples": [
        "--prop tooltip=\"Opens the report\""
      ],
      "readback": "tooltip text string",
      "enforcement": "report"
    },
    "text": {
      "type": "string",
      "description": "display text. Defaults to url or anchor value if omitted.",
      "add": true,
      "set": true,
      "get": true,
      "examples": [
        "--prop text=\"click here\""
      ],
      "readback": "concatenated run text",
      "enforcement": "report"
    },
    "rStyle": {
      "type": "string",
      "description": "Run style id applied to the hyperlink's run (typically 'Hyperlink' to inherit theme color/underline).",
      "add": true,
      "set": false,
      "get": true,
      "examples": [
        "--prop rStyle=Hyperlink"
      ],
      "readback": "style id",
      "enforcement": "report"
    },
    "color": {
      "type": "color",
      "description": "override link color (default: theme Hyperlink or 0563C1). Set after Add not supported — formatting lives on inner runs (Set the run, not the hyperlink wrapper).",
      "add": true,
      "set": false,
      "get": true,
      "examples": [
        "--prop color=#0000FF"
      ],
      "readback": "#-prefixed uppercase hex, or scheme color name (e.g. 'hyperlink', 'followedhyperlink') when using theme default",
      "enforcement": "report"
    },
    "font": {
      "type": "string",
      "add": true,
      "set": false,
      "get": true,
      "examples": [
        "--prop font=\"Calibri\""
      ],
      "readback": "font name",
      "enforcement": "report",
      "description": " Set after Add not supported — formatting lives on inner runs (Set the run, not the hyperlink wrapper)."
    },
    "size": {
      "type": "length",
      "add": true,
      "set": false,
      "get": true,
      "examples": [
        "--prop size=11"
      ],
      "readback": "unit-qualified pt",
      "enforcement": "report",
      "description": " Set after Add not supported — formatting lives on inner runs (Set the run, not the hyperlink wrapper)."
    },
    "underline": {
      "type": "enum",
      "description": "underline style for the link's run. Defaults to single when omitted (theme Hyperlink look). Set after Add not supported — formatting lives on inner runs (Set the run, not the hyperlink wrapper). Aliases: font.underline.",
      "values": [
        "single",
        "double",
        "dotted",
        "dash",
        "wave",
        "none",
        "thick",
        "dottedHeavy",
        "dashLong",
        "dashLongHeavy",
        "dashDotHeavy",
        "wavyHeavy",
        "wavyDouble"
      ],
      "aliases": [
        "font.underline"
      ],
      "add": true,
      "set": false,
      "get": true,
      "examples": [
        "--prop underline=dotted",
        "--prop underline=wave"
      ],
      "readback": "underline style name",
      "enforcement": "report"
    },
    "bold": {
      "type": "bool",
      "add": true,
      "set": false,
      "get": true,
      "examples": [
        "--prop bold=true"
      ],
      "readback": "true/false",
      "enforcement": "report",
      "description": " Set after Add not supported — formatting lives on inner runs (Set the run, not the hyperlink wrapper)."
    },
    "italic": {
      "type": "bool",
      "add": true,
      "set": false,
      "get": true,
      "examples": [
        "--prop italic=true"
      ],
      "readback": "true/false",
      "enforcement": "report",
      "description": " Set after Add not supported — formatting lives on inner runs (Set the run, not the hyperlink wrapper)."
    },
    "docLocation": {
      "type": "string",
      "description": "w:docLocation — frame name (or location-within-document for non-text-anchor refs). Preserved on dump round-trip. Get only; set via the underlying hyperlink rewrite path on Add.",
      "aliases": ["doclocation"],
      "add": false,
      "set": false,
      "get": true,
      "readback": "doc location string",
      "enforcement": "report"
    }
  }
}