Compatibility Dump Contract

OpenMeta exposes a deterministic text dump for downstream compatibility tests. The goal is to let host projects compare names, value shapes, origins, and transfer decisions without keeping binary metadata packet baselines.

Contract constant:

openmeta::kCompatibilityDumpContractVersion == 1

Python exposes the same version as:

openmeta.COMPATIBILITY_DUMP_CONTRACT_VERSION == 1

Metadata dump

Use dump_metadata_compatibility(...) for C++:

#include "openmeta/compatibility_dump.h"

openmeta::MetadataCompatibilityDumpOptions options;
options.style = openmeta::ExportNameStyle::FlatHost;

std::string out;
openmeta::dump_metadata_compatibility(store, options, &out);

Python Document and TransferSourceSnapshot expose the same metadata dump:

doc = openmeta.read("source.jpg")
text = doc.compatibility_dump()

The v1 metadata dump is line-oriented ASCII text:

openmeta.compat.metadata version=1 ...
entry index=0 name="Make" key_kind="exif_tag" value_kind="text" ...

Each emitted entry is based on visit_metadata(...), so ordering, duplicate handling, and naming follow the selected ExportNameStyle. By default the dump uses the stable FlatHost contract.

Metadata entry lines include:

  • exported name

  • key family

  • value kind

  • scalar or array element type

  • text encoding

  • count

  • optional safe value text

  • optional origin block/order/wire fields

  • optional per-entry flags

Text and byte values are escaped with the same terminal-safe ASCII rules used by other OpenMeta diagnostic output. Large values are bounded by max_value_bytes.

Transfer dump

Use dump_transfer_compatibility(...) for C++ transfer/writeback decisions:

std::string out;
openmeta::TransferCompatibilityDumpOptions options;
openmeta::dump_transfer_compatibility(
    result, persisted_or_null, options, &out);

The v1 transfer dump is line-oriented ASCII text:

openmeta.compat.transfer version=1 target_format="png" ...
policy index=0 subject="xmp_iptc_projection" ...
block index=0 kind="xmp" route="png:itxt-xmp" ...
execute edit_requested=true ...
writeback xmp_sidecar_requested=true ...
persist status="ok" ...

Transfer dump lines include:

  • target format and high-level read/prepare status

  • prepared policy decisions

  • prepared block kind, route, order, and payload size

  • execute/edit status and output sizes

  • XMP sidecar request, output, and cleanup decisions

  • optional persisted file/sidecar/cleanup result

The dump intentionally records decisions and sizes, not full binary payloads. This keeps downstream tests stable across equivalent packet serialization changes.

Stability

This is a stable v1 contract. Future releases may add fields or lines, but existing v1 field names and meanings should not change without a new contract version or a documented compatibility path.