Comparing Metadata Between Document Versions - Technical Deep Dive Leave feedback

Note

💡 Full working example available on GitHub: document-version-metadata-diff-python

Metadata version comparison is a GroupDocs.Metadata capability for Python via .NET that reads every property of two document revisions and reports exactly what was added, removed, or changed between them. Properties like Creator, RevisionNumber, and the last-printed timestamp never render on the page, yet they are the first thing an auditor asks about — and reading them by hand means a new code branch per format. This guide dissects a compact pipeline instead: one extraction call flattens each revision’s property tree, a pure-Python diff classifies the result, two tag-driven detectors isolate identity and activity signals, and two exporters serialize the verdict. Every code block comes from the runnable repository above, which ships with two sample DOCX revisions and asserts all six functions on every run. The audience is engineers building compliance tooling who need evidence-grade output rather than a visual compare.

Warning

For Production Use: run the complete implementation against your own document corpus before deployment.

One question: given two versions of the same file, what changed about it, and can you prove it? For audit-trail, retention, and tampering work — not body-text comparison, which is a different problem.

Prerequisites:

• Python 3 with pip; the demo pins groupdocs-metadata-net==26.5 in requirements.txt
• A GroupDocs license file (optional — without one the demo runs in evaluation mode and says so)

pip install groupdocs-metadata-net==26.5

Point LICENSE_PATH in main.py at your .lic file, then run python main.py. It diffs the two bundled DOCX revisions, writes output/diff.json and output/diff.csv, and prints ALL PASS when all six stages hold.

document-version-metadata-diff-python/
├── main.py
├── methods/
│   ├── compare_metadata_sets.py
│   ├── detect_ownership_changes.py
│   ├── detect_revision_history.py
│   ├── export_diff_to_csv.py
│   ├── export_diff_to_json.py
│   └── extract_all_metadata.py
├── requirements.txt
└── resources/          # document-v1.docx, document-v2.docx

Only this component understands file formats, and it delegates that to the Metadata class: one find_properties call walks built-in, custom, and format-specific packages in a single pass, flattened into a dict keyed by qualified name. interpreted_value makes dates and enumerations comparable strings, and nothing here names a format — see Extracting metadata for the mechanism.

Design Pattern: Adapter over format-specific packages Concurrency Model: Synchronous, single file handle State Management: Stateless

result = {}
with Metadata(document_path) as metadata:
    for prop in metadata.find_properties(lambda p: p.name is not None):
        key = prop.name
        value = (str(prop.interpreted_value)
                 if prop.interpreted_value is not None
                 else (str(prop.value) if prop.value is not None else ""))
        result[key] = value
return result

Cost is dominated by opening the file; body content is never rendered. Scaling is linear and embarrassingly parallel — a pool over 10,000 documents shares no state, and storage latency, not CPU, is the bottleneck.

The diff core never touches a file: both revisions become name→value maps, classified into three buckets on a MetadataDiff value object — added, removed, changed (old/new pairs) — with total_changes as a one-number verdict. A structured object instead of a report string is the decision the rest of the pipeline leans on.

Design Pattern: Value object with set-classification Concurrency Model: Pure in-memory computation

v1 = extract_all_metadata(path_v1)
v2 = extract_all_metadata(path_v2)
diff = MetadataDiff()

for k, v in v2.items():
    if k not in v1:
        diff.added[k] = v
    elif v1[k] != v:
        diff.changed[k] = (v1[k], v)

for k, v in v1.items():
    if k not in v2:
        diff.removed[k] = v

return diff

Two dictionary scans over a few hundred entries — unmeasurable next to the file reads. In a batch service, expose this component: two paths in, one serialized diff out.

The detectors answer what auditors ask first: who touched the file, and when. detect_ownership_changes narrows to identity properties via tag predicates — Tags.person.creator, Tags.person.editor, Tags.person.manager, Tags.corporate.company — while detect_revision_history targets time tags plus name patterns for revision counters. No format-specific key like dc:creator appears in the code; the tag finds the right property per format, as covered in Find metadata properties. A <missing> sentinel separates a deleted property from a blanked one.

Design Pattern: Predicate-filtered projection Concurrency Model: Synchronous, one filtered read per file

The ownership comparison:

v1 = _read_ownership(path_v1)
v2 = _read_ownership(path_v2)
all_keys = set(v1.keys()) | set(v2.keys())
changes = {}
for k in all_keys:
    old_v = v1.get(k, "<missing>")
    new_v = v2.get(k, "<missing>")
    if old_v != new_v:
        changes[k] = (old_v, new_v)
return changes

Its tag-filtered reader:

result = {}
with Metadata(path) as metadata:
    props = metadata.find_properties(lambda p:
        Tags.person.creator in list(p.tags)
        or Tags.person.editor in list(p.tags)
        or Tags.person.manager in list(p.tags)
        or Tags.corporate.company in list(p.tags))
    for prop in props:
        value = (str(prop.interpreted_value)
                 if prop.interpreted_value is not None
                 else (str(prop.value) if prop.value is not None else ""))
        result[prop.name] = value
return result

The revision detector swaps the predicate — time tags composed with plain string checks:

props = metadata.find_properties(lambda p:
    Tags.time.modified in list(p.tags)
    or Tags.time.created in list(p.tags)
    or Tags.time.printed in list(p.tags)
    or (p.name is not None and
        ("Revision" in p.name or "EditTime" in p.name
         or "EditingTime" in p.name)))

Each detector re-opens its files — the trade-off for standalone functions. At audit scale, extract once per revision and filter the in-memory dicts instead.

Two serializers, one MetadataDiff. JSON keeps the three buckets as top-level maps with explicit from/to fields — stable enough to diff across audit runs. CSV flattens to one row per change with four fixed columns for Excel, warehouse jobs, or a SIEM. Both use only the standard library.

payload = {
    "added": diff.added,
    "removed": diff.removed,
    "changed": {k: {"from": v[0], "to": v[1]} for k, v in diff.changed.items()},
}
with open(output_path, "w", encoding="utf-8") as f:
    json.dump(payload, f, indent=2, ensure_ascii=False)

with open(output_path, "w", encoding="utf-8", newline="") as f:
    writer = csv.writer(f)
    writer.writerow(["change_type", "property", "old_value", "new_value"])
    for k, v in diff.added.items():
        writer.writerow(["added", k, "", v])
    for k, v in diff.removed.items():
        writer.writerow(["removed", k, v, ""])
    for k, (old_v, new_v) in diff.changed.items():
        writer.writerow(["changed", k, old_v, new_v])

• Monitoring: a corpus-wide total_changes spike usually means a bulk process rewrote properties.
• Error Handling: main.py asserts every stage and exits non-zero — a ready-made CI smoke test.
• Resilience: exports are idempotent; re-runs overwrite the same two files.

Run both revisions through detect_ownership_changes and detect_revision_history, then export the combined diff. The first reports every identity property whose value differs — Creator, Editor, Manager, Company — with old and new values side by side; the second shows the activity trail: revision counters, editing time, created, modified, and printed timestamps. Together they answer who and when in two function calls, with output you can attach to a case file.

Reach for a metadata diff when the dispute is about the file, not the words in it: chain-of-custody checks, retention audits, contested authorship, or a screen before full e-discovery review. It also wins on volume — no rendering, so a folder of contracts screens in minutes. Use GroupDocs.Comparison for paragraph-level content changes, and both when a claim needs content and property evidence to line up. I default to the metadata pass first; its verdict tells you whether the expensive content review is needed at all.

• Comparing raw values instead of interpreted_value — raw objects differ across formats; the string projection lines up.
• Hard-coding property names — Author in one format is dc:creator in another; tag predicates survive both.
• Treating “missing” as “empty” — a removed property and a blanked one are different findings; hence the sentinel.
• Forgetting newline="" in the CSV writer — without it every row on Windows gains a blank line.
• Concluding from evaluation mode — unlicensed runs limit some properties; license before attaching output to a finding.

The pipeline only reads its inputs — originals stay untouched and defensible. Store the exports under access control and hash them if they enter a legal hold. For the reverse obligation — stripping properties before release — the same search engine drives the removing metadata workflow.

Does this work for formats other than DOCX? Yes — nothing in the pipeline names a format. The Metadata constructor detects the type, and the product documentation lists 170+ formats including PDF, XLSX, PPTX, images, and audio. The samples are DOCX because Office files carry the richest built-in property sets.

Why do the detectors re-open files instead of reusing the extraction? Each function stands alone so it can be lifted into another codebase, at the cost of two extra file opens. At scale, extract once per revision and filter the in-memory dicts. The classification logic stays identical.

Can I diff two arbitrary documents rather than two versions of one file? Mechanically yes — the diff has no notion of lineage. But unrelated files report nearly everything as added or changed, so the output only means something for related inputs. Ground the “v1”/“v2” labels in version-control or DMS history first.

Six small functions cover the audit path: flatten, diff, filter for identity, filter for activity, serialize twice. The decisions that make it hold up are unglamorous — interpreted values, a structured diff object, tag predicates, an explicit missing sentinel. Before deployment, review the complete source code, extract once per file at batch scale, and store exports with the same controls as the documents they describe.

• In-depth blog article about this project – the business case behind the pipeline
• Find metadata properties – the tag catalog both detectors rely on
• Extracting metadata – the extraction API in depth
• Product documentation – getting started and advanced topics
• API Reference – full API details for GroupDocs.Metadata for Python via .NET
• GitHub repository – complete source code and sample documents