Writer Target Contract¶
This page defines the bounded preserve/replace contract for OpenMeta transfer writers.
It is scoped to metadata transfer and metadata-only target edits. OpenMeta does not claim full arbitrary metadata-editor parity, pixel transcoding, or byte-for-byte preservation of rewritten metadata structures.
For generated XMP merge, precedence, sidecar output, and sidecar cleanup rules, see XMP Sync And Writeback Policy.
Common Rules¶
Managed metadata families are replaced only when OpenMeta has a prepared block for that family or an explicit strip policy targets that family.
Unmanaged data is preserved as source ranges where the target edit path can parse the container safely. If parsing finds a structure outside the bounded contract, the edit fails with an unsupported or malformed result instead of guessing.
Managed XMP writeback has three modes:
EmbeddedOnly: generated XMP remains in the managed embedded carrier.SidecarOnly: generated embedded XMP blocks are suppressed and returned as sidecar output.EmbeddedAndSidecar: generated XMP is written to both the embedded carrier and sidecar output.
Destination embedded-XMP stripping is supported only for sidecar-only writeback on JPEG, TIFF/DNG, PNG, WebP, JP2, JXL, and bounded BMFF targets. Destination sidecar cleanup is supported only for embedded writeback.
Image-dependent metadata is target-owned. When source and target images may
differ in dimensions, channel count, sample type, compression, orientation,
colorspace, or strip/tile storage layout, host code must preserve or provide
target-correct image buffer specs from the actual output image. Use
PrepareTransferRequest::target_image_spec when the host knows target
dimensions, orientation, samples-per-pixel, bit depth, sample format,
photometric interpretation, planar configuration, compression, or EXIF color
space. OpenMeta filters source EXIF/XMP image-layout fields during prepared
transfer rather than copying stale source width/height, channel/layout,
color-space aliases, or source-local storage offsets into another file. ICC
transfer should be enabled only when the host knows that the source profile is
valid for the target pixel buffer; otherwise the host writer should keep or
inject the target profile. The Python binding exposes the same structure as
openmeta.TransferTargetImageSpec; the C++ and Python metatransfer
command wrappers expose matching --target-* flags for smoke tests and
file-helper integration checks.
For coarse transfer safety, use TransferProfile::safety. The default
CompatibleFile mode is for metadata repackage or recompression into a
compatible target and preserves source camera/color metadata after the
target-owned image-layout filter above. RenderedImage is for exports whose
pixels may have changed, including RAW-to-rendered outputs. It keeps general
descriptive metadata, time fields, GPS, IPTC, and portable XMP, but filters
source raw color calibration, profile/gain tables, raw digests/storage
identifiers, linearization/crop/correction tags, vendor RAW
geometry/color/correction/private tags for Phase One/Leaf, Sony, Canon, Nikon,
Fujifilm, Pentax, Panasonic, Olympus, Kodak, Minolta, Sigma, Samsung, Ricoh,
Apple/Google computational capture fields, DJI/FLIR thermal processing fields,
Casio/Sanyo preview or face-geometry fields, KyoceraRaw WB fields, Reconyx
trail-camera processing/environment fields, HP/JVC/GE private placeholders,
Motorola source-rendering/sensor fields, Nintendo parallax/camera-info fields,
Microsoft stitch/panorama geometry fields, camera raw settings XMP, source ICC
profiles, MakerNotes, and non-C2PA JUMBF data. Host code should provide
target-correct ICC/profile data and image specs separately.
Transfer Safety Matrix¶
The table below is the public coarse policy for automatic transfer. It is not
a privacy policy and it is not a replacement for application-specific metadata
controls. Hosts may still strip more metadata. For per-candidate preflight UI,
metadata_concepts.h exposes transfer hints such as safe,
source_bound, rendered_unsafe, and requires_target_image_spec;
transfer_concept_diagnostics_from_store(...) maps those hints to
keep/drop/requires-target-image-spec actions, severity tokens, and default
message text for a selected transfer mode.
Metadata group |
Examples |
|
|
Notes |
|---|---|---|---|---|
General descriptive metadata |
title, description, creator, artist, copyright, rating, label, keywords |
Keep |
Keep |
Safe because it describes the asset or authorship rather than the source pixel encoding. |
Capture time |
|
Keep |
Keep |
If the output represents a new capture or synthetic composition, host policy should replace or strip these values. |
Camera and lens acquisition facts |
|
Keep |
Keep |
These are safe as capture facts. They are not treated as processing instructions. |
Location and IPTC editorial fields |
EXIF GPS, XMP GPS aliases, IPTC location, caption, byline, credit, rights, job/reference fields |
Keep |
Keep |
Privacy-sensitive data is intentionally left to host policy. |
Portable XMP |
Dublin Core, XMP Rights, IPTC Extension, generated EXIF/IPTC projections |
Keep after image-layout filtering |
Keep after image-layout and rendered-safety filtering |
XMP properties from raw-processing namespaces are handled separately below. |
Target image layout and storage |
width, height, orientation, samples per pixel, bits per sample, sample format, photometric interpretation, compression, rows/strips/tiles, offsets, byte counts, thumbnail/interchange offsets |
Target-owned; source values filtered |
Target-owned; source values filtered |
Host code must preserve target values or provide
|
Output color/profile metadata |
ICC profile blocks, EXIF/XMP |
Keep only when the source profile is valid for the target pixel buffer |
Drop source ICC/profile facts; host writes target profile |
Rendered exports often need a new output profile such as sRGB, Display P3, or a host-managed working/output profile. |
RAW/DNG sensor and color pipeline |
CFA pattern, black/white levels, linearization tables,
|
Keep only for compatible RAW/DNG-style transfer |
Drop |
These values describe how to turn original sensor data into rendered color. Reusing them on already-rendered pixels can make CMS or editors apply the raw transform twice. |
RAW crop, geometry, storage, correction, and private data |
|
Keep only for compatible RAW/DNG-style transfer |
Drop |
These values are tied to the original sensor geometry and raw-processing
pipeline. Vendor-private RAW/source tables are dropped in rendered mode
even when individual fields are unknown, while named entries also
receive narrower color/WB/geometry/correction buckets. Use
|
Camera raw settings XMP |
|
Keep |
Drop |
A rendered file should not normally carry a source raw-edit recipe unless the host intentionally writes a sidecar/workflow record. |
Opaque MakerNote payloads |
vendor MakerNote blobs and private nested IFDs |
Keep the original raw |
Drop |
Decoded safe facts can still be carried through standard EXIF/XMP fields; the opaque vendor blob is not copied for rendered outputs. Decoded-only vendor MakerNote sub-IFDs are not reconstructed into a new blob; prepare reports them as non-serializable when no raw MakerNote payload is available. |
C2PA and JUMBF |
APP11/JUMBF boxes, C2PA manifests, assertions, signatures |
Follow explicit JUMBF/C2PA policy |
Drop non-C2PA JUMBF; invalidate C2PA by default if it would otherwise be kept |
Pixel-changing exports need a new content binding and signature from the host or signer. |
Embedded previews and thumbnails |
TIFF preview pages, SubIFD previews, JPEG interchange thumbnail data |
Preserve only within bounded target-owned rewrite rules |
Target-owned; host should regenerate or preserve target previews |
Source previews commonly describe the source pixels, not the rendered target. |
Target Summary¶
Target |
Managed embedded carriers |
Preserve/replace rule |
Main limits |
|---|---|---|---|
|
APP1 EXIF, APP1 XMP, APP2 ICC, APP13 IPTC/IRB, bounded APP11 JUMBF/C2PA |
Replace matching recognized leading metadata segments; preserve unknown leading segments and image scan data. |
Not a general JPEG marker editor. |
|
root TIFF tags, EXIF/GPS/Interop IFDs, bounded page/SubIFD chains, XMP tag 700, IPTC 33723, ICC 34675 |
Rewrite bounded IFD structures and append new metadata tail data; preserve unrelated root tags and bounded downstream tails. |
Not arbitrary nested-IFD graph rewrite. |
|
same as TIFF plus DNG target-mode policy and minimal |
Uses the TIFF-family rewrite contract; preserves DNG core target tags when merging non-DNG source metadata into an existing DNG target. |
Not a full DNG-specific rewrite engine. |
|
|
Insert prepared chunks after |
Requires valid PNG with terminal |
|
|
Replace matching managed RIFF chunks; preserve unrelated chunks; patch
|
EXIF/XMP/ICC edits require an existing |
|
top-level |
Replace matching top-level metadata boxes; rewrite |
Does not synthesize |
|
top-level |
Replace matching top-level boxes; preserve signature and non-managed
boxes; classify |
ICC is encoder handoff only; file edit emits uncompressed prepared metadata boxes. |
|
BMFF metadata items ( |
Preserve non- |
Does not rewrite arbitrary BMFF scene/property graphs. |
|
safe string header attributes through the EXR transfer emitter or adapter batch |
No file rewrite contract today; host applies prepared attributes through its own EXR writer. |
Attribute-emitter target, not a file edit path. |
JPEG¶
The JPEG edit path scans leading metadata marker segments before image scan data.
OpenMeta replaces a leading segment when:
the segment route matches a prepared block route
sidecar-only writeback requests embedded XMP stripping and the segment is APP1 XMP
JUMBF or C2PA policy resolves to removal for matching APP11 carriers
Unknown APP/COM segments and all scan data after the leading metadata region are preserved. If same-size replacements are available, OpenMeta can use the in-place edit plan; otherwise it performs a metadata rewrite while preserving the image data range.
TIFF And DNG¶
TIFF-family editing supports classic TIFF and BigTIFF.
Managed updates include:
root IFD metadata tags such as XMP tag 700, IPTC tag 33723, and ICC tag 34675
EXIF payload materialized as bounded TIFF-family IFD structures
EXIF/GPS/Interop pointer regeneration
bounded preview-page chain replacement with downstream tail preservation
bounded
SubIFDreplacement with downstream auxiliary-tail preservationpreserving an existing target
InteropIFDwhen a replacedExifIFDomits its own interop child
The active root image IFD remains target-owned for pixel layout and local byte
storage. Source EXIF values for root image width/height, sample layout,
compression, orientation, strip/tile offsets, strip/tile byte counts, and
thumbnail/JPEG interchange offsets are not allowed to replace the target’s
active image structure during metadata transfer. For replaced preview-page and
SubIFD structures, OpenMeta also strips source-local strip/tile/JPEG
storage offsets and preserves the corresponding target-local storage fields
when a matching target child exists.
The same target-owned rule is applied before packaging EXIF/XMP metadata for
JPEG, PNG, WebP, JP2, JXL, BMFF-family targets, and EXR string attributes.
Source descriptive tags such as make/model/date/GPS/copyright continue to
transfer; source image-buffer facts do not become target image facts unless a
host supplies target-correct values through target_image_spec or another
writer-specific path.
Unrelated root IFD tags are preserved. Rewritten structures may be repacked into new offsets appended to the file; offset identity is not part of the contract.
DNG uses the same TIFF-family rewrite contract. ExistingTarget and
TemplateTarget require a backing target container. MinimalFreshScaffold
can emit a minimal metadata scaffold without an existing DNG target. When a
non-DNG source is merged into an existing DNG target, OpenMeta preserves
existing target DNG core tags within the bounded DNG policy layer.
PNG¶
The PNG edit path requires a valid PNG signature, an IHDR chunk, and a
terminal IEND chunk.
Prepared eXIf, XMP iTXt, and iCCP chunks are inserted immediately
after IHDR. Existing chunks from those managed families are removed when a
replacement or strip policy targets that family. XMP matching is limited to
iTXt chunks using the XML:com.adobe.xmp keyword.
All unrelated chunks are preserved. Bytes following the terminal IEND are
preserved as part of the kept terminal range.
WebP¶
The WebP edit path requires a valid RIFF/WebP stream whose RIFF size consumes the input bytes.
Prepared EXIF, XMP, ICCP, and bounded C2PA chunks replace
existing chunks from the same managed family. Unrelated chunks are preserved.
When EXIF, XMP, or ICC is present after rewrite, OpenMeta patches the existing
VP8X feature flags to match the final metadata state.
Prepared WebP EXIF chunks carry the TIFF byte stream directly. They do
not include the JPEG APP1 Exif\0\0 preamble.
The current WebP edit contract requires an existing VP8X chunk for EXIF,
XMP, or ICC metadata edits. It does not synthesize VP8X.
JP2¶
The JP2 edit path requires a valid JP2 signature box and file-type box.
Prepared top-level Exif and XMP xml boxes replace existing top-level
boxes from the same managed family. Unrelated top-level boxes are preserved.
ICC update uses the bounded jp2h/colr route. OpenMeta rewrites the
existing jp2h box to replace existing colr children with the prepared
ICC colr payload, while preserving unrelated jp2h children. If no
colr child exists, the prepared colr child is inserted. The contract
requires one existing jp2h box and does not synthesize a new jp2h box.
JXL¶
The JXL edit path requires a valid JXL container.
Prepared top-level Exif, XMP xml, jumb, and c2pa boxes replace
existing boxes from the same managed family. Unrelated top-level boxes are
preserved, including the JXL signature box. Generic JUMBF and C2PA are
distinguished so a generic jumb replacement does not accidentally remove a
C2PA carrier, and the C2PA path does not remove unrelated generic JUMBF.
When Brotli support is available, the same family classification can inspect
compressed brob metadata boxes by real type. The file edit path emits
prepared metadata boxes directly; the jxl:icc-profile route remains an
encoder-side handoff and is not serialized by the file edit path.
HEIF / AVIF / CR3¶
The bounded BMFF edit path preserves non-meta top-level boxes as source
ranges.
When the target has no foreign top-level meta box, OpenMeta writes one
metadata-only top-level meta box using the public bounded contract. That
box can contain prepared Exif, XMP, JUMBF, C2PA, and ICC colr property
payloads. A prior OpenMeta-authored metadata meta box is removed and
replaced by the newly prepared box.
When the target already has a foreign top-level meta box, OpenMeta does
not append a second competing meta graph. For parseable HEIF/AVIF-style
item graphs it merges, replaces, or strips bounded Exif/XMP/JUMBF/C2PA
metadata items in the existing meta by extending iinf, iloc,
idat, and iref with cdsc references to the primary item. This
constrained merge requires a single parseable iinf, iloc version
0/1/2, pitm, and at most one idat. When inserted metadata needs an item
ID wider than 16 bits, OpenMeta upgrades the rebuilt iloc to version 2,
emits infe version 3 for those inserted items, and uses iref version 1
for the corresponding cdsc references. If the existing graph has exhausted
the usable 32-bit item-id space or mixes item-table shapes outside this bounded
contract, the edit fails instead of truncating IDs.
Newly inserted metadata item payloads are appended to the rebuilt idat
payload. To preserve broad reader compatibility, their iloc records keep
construction method 0 and use absolute file-offset extents within the existing
field widths. When all retained self-contained item locations can be
represented as absolute extents, OpenMeta compacts the rebuilt iloc
base-offset field width to zero for simpler reader compatibility.
Retained foreign item locations are supported when they use construction
method 0 with file offsets, or construction method 1 with offsets into an
existing idat, with data reference index 0. Construction method 2 is
supported only when the retained item has parseable iref iloc
references, using explicit extent indexes or reference order, and every
referenced item is also retained with a supported local location. External
data references, missing method-2 references, removed referenced items, and
other construction methods fail as unsupported instead of being rewritten by
guesswork.
For bounded ICC transfer, OpenMeta removes prior ICC colr/prof and
colr/rICC properties from iprp/ipco, compacts/remaps existing ipma
associations, appends the transferred colr/prof property, and associates it
with the primary item and any retained item that previously referenced one of
the replaced ICC properties. If the replaced association was marked essential,
the transferred ICC association keeps that bit. Arbitrary non-ICC property
replacement and broader BMFF scene/property graph rewriting remain out of
scope.
If sidecar-only writeback asks to strip embedded XMP, OpenMeta can remove XMP
from its own OpenMeta-authored metadata meta box and from parseable
foreign top-level meta item graphs that satisfy the same bounded
primary-item contract. Foreign graphs without pitm, with unsupported
iloc, with multiple competing item tables, or otherwise outside that
bounded shape are reported as unsupported instead of being guessed.
EXR¶
EXR is a transfer target and host-emitter path, not a file rewrite path.
OpenMeta prepares safe flattened string attributes for transfer and exposes the EXR attribute batch helpers for host-owned EXR writers. Existing EXR file metadata preservation is therefore owned by the host writer, not by an OpenMeta file edit helper.
One important pending use case is late-bound EXR metadata. Streaming tile or
scanline writers sometimes only know a value after pixel data is finished,
for example total_compute_time. The safe fast design is a fixed-size
reservation/patch contract: reserve a typed attribute, such as a double,
before writer construction, then patch exactly those value bytes after close.
OpenMeta does not provide this patch API yet; it should remain separate from
general EXR file rewrite because variable-length header changes would require
moving later file structures.
Non-Goals¶
The writer contract does not promise:
arbitrary metadata editing for every carrier a format can contain
preserving byte offsets of rewritten TIFF-family structures
rewriting arbitrary existing BMFF item/property graphs
synthesizing missing JP2
jp2hor WebPVP8Xstructuresfile-level EXR metadata rewrite
signed C2PA rewrite or trust-policy parity beyond the bounded staged handoff paths