docx/custom-document-property

Metadata

XPath assertions

Render assertions

No render assertions declared.

Generator source

scripts/gen_custom_document_property.py

#!/usr/bin/env python3
"""Generate ``fixtures/docx/custom-document-property.docx``.

A minimal document exercising the OPC custom-properties part. Adds one
user-defined property ``TestProperty`` with the string value ``test value``.
The feature is metadata-only; ``word/document.xml`` content is irrelevant.
Designed to satisfy the assertions in
``features/docx/custom-document-property.json``.
"""

from __future__ import annotations

from pathlib import Path

from docx import Document

_REPO_ROOT = Path(__file__).resolve().parent.parent
_OUT = _REPO_ROOT / "fixtures" / "docx" / "custom-document-property.docx"


def main() -> int:
    doc = Document()
    doc.custom_properties["TestProperty"] = "test value"
    doc.add_paragraph("Body content; custom property is the feature under test.")
    _OUT.parent.mkdir(parents=True, exist_ok=True)
    doc.save(_OUT, reproducible=True)
    print(_OUT)
    return 0


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

Manifest (expanded)

{
  "$schema": "../manifest.schema.json",
  "id": "docx/custom-document-property",
  "title": "Custom document property (string)",
  "format": "docx",
  "category": "metadata",
  "summary": "The document carries a single user-defined custom property 'TestProperty' whose value is the string 'test value'.",
  "spec": {
    "source": "ecma-376-5-part-2",
    "clause": "11.2",
    "element": "op:property",
    "notes": "ECMA-376 Part 2 (OPC) defines the custom-properties part at 'docProps/custom.xml' with the 'op' namespace (officeDocument/2006/custom-properties) for the <op:properties>/<op:property> container and 'vt' (officeDocument/2006/docPropsVTypes) for the typed value elements. A string property is serialised as <vt:lpwstr>. Each property must also declare a unique 'pid' (>= 2) and a 'fmtid' attribute, but those are implementation details; the assertion here targets the name/value pair, which is the user-visible surface."
  },
  "fixtures": {
    "machine": "docx/custom-document-property",
    "office": "docx/custom-document-property"
  },
  "generator": {
    "python": "scripts/gen_custom_document_property.py"
  },
  "assertions": [
    {
      "id": "custom-property-present",
      "part": "docProps/custom.xml",
      "namespaces": {
        "op": "http://schemas.openxmlformats.org/officeDocument/2006/custom-properties",
        "vt": "http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes"
      },
      "xpath": "//op:property[@name='TestProperty']",
      "must": "exist",
      "description": "The custom-properties part must carry an <op:property> element whose name='TestProperty'."
    },
    {
      "id": "custom-property-value",
      "part": "docProps/custom.xml",
      "namespaces": {
        "op": "http://schemas.openxmlformats.org/officeDocument/2006/custom-properties",
        "vt": "http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes"
      },
      "xpath": "//op:property[@name='TestProperty']/vt:lpwstr",
      "must": "equal",
      "value": "test value",
      "description": "The TestProperty property's <vt:lpwstr> child must hold the literal string 'test value'."
    }
  ]
}