FlatHost Mapping Contract

ExportNameStyle::FlatHost is the stable v1 naming contract for host-owned metadata object models that prefer flat attribute names over OpenMeta’s native key shapes.

Contract constant:

openmeta::kFlatHostExportContractVersion == 1

Scope

The contract covers names emitted by:

openmeta::visit_metadata(store, options, sink)

with:

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

Python mirrors this name contract through:

doc.export_names(style=openmeta.ExportNameStyle.FlatHost)

The C++ traversal exposes ExportItem::entry, so C++ hosts can project values from the original Entry::value. Python export_names(...) is name-only.

Ordering and duplicates

  • Entries are emitted in MetaStore::entries() order.

  • Deleted entries are skipped.

  • Duplicate names are preserved and emitted separately.

  • OpenMeta does not merge, reconcile, or suffix duplicate FlatHost names.

  • If a host requires unique keys, it must apply its own deterministic collision policy after traversal.

Value projection

FlatHost is a naming contract, not a value-conversion contract.

  • C++ receives the original Entry through ExportItem::entry.

  • Entry::value.kind, elem_type, count, and storage are unchanged.

  • Text encoding remains the original decoded TextEncoding.

  • Byte payloads remain byte payloads; unsafe text conversion is not performed by visit_metadata(...).

  • Hosts that need a text-only export should use a safe formatting layer on top of Entry::value.

Namespace behavior

FlatHost intentionally keeps common camera-style names short while preserving namespace prefixes where ambiguity matters.

Source family

FlatHost rule

TIFF root and preview IFD tags

Use the known tag alias without a prefix, for example Make, ModifyDate, ImageWidth.

EXIF and interoperability IFD tags

Prefix with Exif:, for example Exif:ExposureTime, Exif:ISO, Exif:CreateDate.

GPS IFD tags

Prefix with GPS:, for example GPS:GPSLatitude.

MakerNote IFDs

Emit only when include_makernotes is true, using MakerNote:<ifd>:<tag-name-or-hex>.

XMP simple properties

Emit selected known namespaces as XMP:, TIFF:, Exif:, or DC: plus the simple property name.

ICC header fields and tags

Emit ICC:<field> or ICC:tag:<signature>.

EXR part 0 known aliases

Map selected standard attributes to common host names, for example owner -> Copyright, capDate -> DateTime, expTime -> ExposureTime.

EXR part 0 unknown attributes

Emit openexr:<name>.

EXR non-zero parts

Emit openexr:part:<index>:<name>.

Unsupported key families

Fall back to the canonical OpenMeta name when one exists.

Complex XMP paths are not flattened. XMP properties are emitted only when the property path is a simple token containing letters, digits, _, or -; paths with /, [, ], or other punctuation are skipped by FlatHost.

Name policy

ExportOptions::name_policy controls tag aliasing:

  • ExportNamePolicy::ExifToolAlias is the default and uses OpenMeta’s ExifTool-compatible aliases where OpenMeta has a clean-room mapping.

  • ExportNamePolicy::Spec preserves native/spec-style tag names where available and uses Tag_0x.... for unknown EXIF tags.

The policy does not change ordering, duplicate preservation, or value projection.

Filtering

FlatHost skips:

  • deleted entries

  • EXIF pointer tags under the default alias policy

  • embedded metadata blob tags such as EXIF-stored XMP, ICC, IPTC, Photoshop IRB, and MakerNote blob tags under the default alias policy

  • MakerNote IFDs when include_makernotes is false

  • complex XMP paths and unknown XMP namespaces

  • selected structural EXR header attributes that are not useful as host metadata attributes, such as channels, compression, and data windows

Stability

This is a stable v1 naming contract. Future OpenMeta releases may add mappings for newly decoded metadata families, but existing v1 names should not change without a new contract version or a documented compatibility path.