xlsx/hyperlink-target-modes

Parameter axes

• scheme (3 values): http, mailto, file-uri

Spec notes

Generator source

scripts/gen_xlsx_hyperlink_target_modes.py — runs with --arg_template --scheme {scheme.id} --url "{scheme.url}" --out fixtures/xlsx/hyperlink-target-modes--{scheme.id}.xlsx

#!/usr/bin/env python3
"""Generate ``fixtures/xlsx/hyperlink-target-modes--<scheme>.xlsx``.

Parameterised across the 3 external-URL schemes described by
``features/xlsx/hyperlink-target-modes.json``: http, mailto, file-uri.

Each fixture is a one-cell workbook with cell A1 hyperlinked to the
requested URL. This emits a worksheet-level <hyperlinks>/<hyperlink/>
entry plus a sibling <Relationship .../hyperlink TargetMode='External'/>.

.. versionadded:: 2026.05.0
"""

from __future__ import annotations

import argparse
import datetime as _dt
from pathlib import Path

from xlsx import Workbook

_REPO_ROOT = Path(__file__).resolve().parent.parent
_REPRODUCIBLE_DT = _dt.datetime(2000, 1, 1, 0, 0, 0)


def _write(url: str, out: Path) -> None:
    wb = Workbook()
    ws = wb.active
    ws.title = "Sheet1"
    ws["A1"] = "Click"
    ws["A1"].hyperlink = url

    out.parent.mkdir(parents=True, exist_ok=True)
    wb.save(out, zip_date_time=_REPRODUCIBLE_DT)


def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument("--scheme", required=True)
    parser.add_argument("--url", required=True)
    parser.add_argument("--out", required=True)
    args = parser.parse_args()

    out_path = Path(args.out)
    if not out_path.is_absolute():
        out_path = _REPO_ROOT / out_path

    _write(args.url, out_path)
    print(out_path)
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

Manifest (parent, unexpanded)

{
  "$schema": "../manifest.schema.json",
  "id": "xlsx/hyperlink-target-modes",
  "kind": "parameterised",
  "title": "Hyperlink relationship TargetMode matrix (xlsx)",
  "format": "xlsx",
  "category": "references",
  "summary": "For each external scheme (http, mailto, file://) an xlsx cell-level hyperlink must emit a <Relationship Type='.../hyperlink' Target='<url>' TargetMode='External'/> in the sibling worksheet rels file, and the in-sheet <hyperlink> element must carry an r:id pointing at it.",
  "spec": {
    "source": "ecma-376-5-part-1",
    "clause": "18.3.1.48",
    "element": "x:hyperlink",
    "rnc_reference": "spec/ecma-376-5/part-1/rnc/SpreadsheetML.rnc",
    "xsd_reference": "spec/ecma-376-5/part-1/xsd/sml.xsd",
    "notes": "Sibling of docx/hyperlink-target-modes and pptx/hyperlink-target-modes. xlsx's hyperlinks block lives at worksheet scope; rels therefore live in xl/worksheets/_rels/<sheet>.xml.rels, not at package root. xlsx/hyperlink-cell covers the external-vs-internal branch of the API; this family instead pins the external TargetMode invariant across the three principal URI schemes that appear in the wild."
  },
  "fixtures": {
    "machine": "xlsx/hyperlink-target-modes"
  },
  "generator": {
    "python": "scripts/gen_xlsx_hyperlink_target_modes.py",
    "arg_template": "--scheme {scheme.id} --url \"{scheme.url}\" --out fixtures/xlsx/hyperlink-target-modes--{scheme.id}.xlsx"
  },
  "parameters": {
    "scheme": [
      {
        "id": "http",
        "url": "https://example.com/path"
      },
      {
        "id": "mailto",
        "url": "mailto:someone@example.com?subject=Hi"
      },
      {
        "id": "file-uri",
        "url": "file:///C:/docs/other.xlsx"
      }
    ]
  },
  "assertions_template": [
    {
      "id": "sheet-hyperlink-has-rid-{scheme.id}",
      "part": "xl/worksheets/sheet1.xml",
      "namespaces": {
        "x": "http://schemas.openxmlformats.org/spreadsheetml/2006/main",
        "r": "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
      },
      "xpath": "//x:hyperlinks/x:hyperlink[@ref='A1'][@r:id]",
      "must": "exist",
      "description": "The cell-level <hyperlink> element must carry an r:id that resolves via the sibling rels file."
    },
    {
      "id": "rel-target-{scheme.id}",
      "part": "xl/worksheets/_rels/sheet1.xml.rels",
      "namespaces": {
        "pr": "http://schemas.openxmlformats.org/package/2006/relationships"
      },
      "xpath": "string(//pr:Relationship[@Type='http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink']/@Target)",
      "must": "equal",
      "value": "{scheme.url}",
      "description": "The worksheet rels file must carry one hyperlink relationship whose @Target equals the generated URL."
    },
    {
      "id": "rel-targetmode-{scheme.id}",
      "part": "xl/worksheets/_rels/sheet1.xml.rels",
      "namespaces": {
        "pr": "http://schemas.openxmlformats.org/package/2006/relationships"
      },
      "xpath": "string(//pr:Relationship[@Type='http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink']/@TargetMode)",
      "must": "equal",
      "value": "External",
      "description": "External hyperlink relationships must carry TargetMode='External'."
    }
  ]
}