This page defines the adoption status for public OpenMeta APIs. Python bindings mirror these labels unless a Python wrapper documents a different status.
| Level | Meaning |
|---|---|
| Stable | Intended for downstream use. Breaking changes require a new contract version, a compatibility path, or a documented migration. |
| Experimental | Public and tested, but the exact shape or semantics may still evolve while the surrounding workflow is being hardened. |
| Internal | Publicly visible only because it is part of a lower-level implementation surface. Do not build new downstream integrations on it unless another doc names it as supported. |
| API surface | Header | Stability | Notes |
|---|---|---|---|
Host Adoption Profile v1: host_adoption_profile(), host_adoption_profile_matches(...) |
openmeta/host_adoption.h |
Stable | Exact compile-time/runtime contract descriptor for the narrow positional read, persistence, reconciliation, diagnostics, and typed codec-operation schema. See host_adoption_profile.md. |
Prepared Transfer Handoff v1: immutable template preparation/replay plus PreparedTransferHandoffInstance creation, exact-width/slot-count field queries, strict fixed-width patches, indexed views, replay, and runtime contract queries |
openmeta/prepared_transfer_handoff.h |
Stable v1 | Move-only opaque owners hide routes and bundle state. Template preparation and worker creation may allocate. Instance query/patch/index/replay allocate nothing; patch batches are exact-width, required-slot, alias-rejecting, and transactional. Independent instances own their payloads and can run concurrently. Raw-carrier passthrough, variable-width/structural mutation, persistence, and destination editing remain outside v1. See prepared_transfer_handoff.md. |
Runtime capability query: metadata_capability(...) |
openmeta/metadata_capabilities.h |
Stable | v1 query contract for read, structured decode, transfer preparation, target edit, and raw-preservation status by format/family. |
Positional source, snapshot, and read diagnostics: RandomAccessSource, source ranges/read windows, random_access_read_exact(...), read_transfer_source_snapshot_random_access(...), and collect_read_transfer_source_diagnostics(...) |
openmeta/random_access_source.h, openmeta/metadata_transfer.h |
Stable v1 | Allocation-free exact callback reads, caller-owned accounting/scratch, owned finalized snapshots, explicit completeness/residual semantics, and caller-buffered structured diagnostics. Format coverage may grow additively. See host_adoption_profile.md and random_access_input.md. |
Low-level positional format decode, payload, and scan APIs: decode_exif_tiff_random_access(...), decode_exr_header_random_access(...), extract_payload_random_access(...), and the scan_*_random_access(...) family |
openmeta/exif_tiff_decode.h, openmeta/exr_decode.h, openmeta/container_payload.h, openmeta/container_scan.h |
Experimental | Format-specific structures and scratch requirements may still evolve. The stable top-level snapshot result exposes unsupported or incomplete lanes as explicit residuals. |
Compatibility dumps: dump_metadata_compatibility(...), dump_transfer_compatibility(...) |
openmeta/compatibility_dump.h |
Stable | Stable v1 line-oriented compatibility dump contract, including generic BMFF component membership, role, relation-summary, policy, derived-image construction, and tiled-image configuration fields as normal bmff_field entries. See compatibility_dump.md. |
XMP sync and writeback policy enums: XmpConflictPolicy, existing-carrier precedence enums, XmpWritebackMode, destination carrier modes |
openmeta/xmp_dump.h, openmeta/metadata_transfer.h |
Stable | Stable bounded writer policy for generated portable XMP. See xmp_sync_policy.md. |
Generic metadata traversal: visit_metadata(...), MetadataSink, ExportOptions, ExportItem |
openmeta/interop_export.h |
Stable | v1 traversal contract. Borrowed names are valid only during MetadataSink::on_item(...). |
ExportNameStyle::Canonical and ExportNameStyle::XmpPortable |
openmeta/interop_export.h |
Stable | Stable naming modes for key-space-aware and portable exports. |
ExportNameStyle::FlatHost |
openmeta/interop_export.h |
Stable | Stable v1 flat host naming contract. See flat_host_mapping.md. |
Typed FlatHost import: import_flat_host_metadata(...) |
openmeta/interop_import.h |
Stable v1 | Transactional detached-store reconciliation. Existing values and tombstones use exact source identity or a unique FlatHost name; duplicate names are rejected, removals retain stable ids/provenance as Dirty | Deleted, and new arbitrary entries require an explicit typed MetaKeyView. |
Fresh metadata creation: create_metadata(...) and typed field helpers |
openmeta/metadata_creation.h |
Experimental | Transactional v1 contract for bounded host-provided logical fields. Produces a finalized canonical portable-XMP MetaStore, preserves additive creator/keyword order, rejects duplicate singletons, validates UTF-8/XML text and typed numeric constraints, and exposes the same C++ policy through a thin Python create_metadata(...) wrapper. Direct EXIF/IPTC projection remains a Translation concern. See creation.md. |
Generic typed metadata authoring: create_metadata_store(...), borrowed key/value helpers, and MetaStore::reserve(...) |
openmeta/metadata_authoring.h, openmeta/meta_key.h, openmeta/meta_value.h, openmeta/meta_store.h |
Experimental v1 | Transactional bounded construction of finalized EXIF/TIFF/DNG-style, XMP, and IPTC-IIM entries. Unknown/private EXIF and custom XMP namespaces remain authorable; safe scalar/indexed custom XMP is supported. Output is replaced only after enabled validation succeeds. C++ only in this milestone. See generic_authoring.md. |
Detached store/schema validation: validate_entry(...), validate_store(...) |
openmeta/validate.h |
Experimental v1 | Structured structural and initial TIFF/EXIF/GPS/DNG/XMP schema diagnostics with resource limits, permissive unknown-tag policy, duplicate-singleton checks, rational/text checks, and optional image/CFA/color context. This does not prove that semantically valid metadata describes the destination pixels. |
Canonical TIFF/EXIF serialization: serialize_exif_tiff(...) |
openmeta/exif_tiff_serialize.h |
Experimental v1 | Deterministic measure/write API for unwrapped little-endian TIFF bytes. The same payload feeds target transfer wrapping; JPEG/TIFF, PNG/WebP, and boxed EXIF framing remain separate. Opaque MakerNotes drop by default. See canonical_serialization.md. |
Prepared TIFF/EXIF and scalar XMP patching: prepare_metadata_patch_plan(...), PreparedMetadataPatchPlan, PreparedMetadataPatchInstance, and patch_prepared_metadata_instance(...) |
openmeta/metadata_patch.h |
Experimental v1 | Target-neutral opaque handles for typed EXIF and emitted scalar XMP values. Preparation and worker creation may allocate; mixed EXIF/XMP batches, payload access and library replay do not. Failed batches change neither payload. Handles expose no offsets and belong to one preparation generation. See canonical_patching.md. |
Logical metadata editing: edit_metadata(...) and add/set/remove helpers |
openmeta/metadata_editing.h |
Experimental | Transactional v1 contract over finalized stores and the Creation logical field map. Set/remove preserve provenance through dirty values and tombstones; add handles deterministic repeated fields and explicit singleton conflicts. Python returns a detached edited Document without mutating its source. See editing.md. |
Exact-key typed editing: edit_metadata_typed(...) |
openmeta/metadata_editing.h |
Experimental v1 | Transactional C++ Add/Set/Remove for supported EXIF/IPTC/XMP and private/custom keys, explicit occurrence/conflict handling, updated wire hints, resource ceilings and complete candidate validation. See editing.md. |
Reverse creation-date translation: translate_xmp_creation_dates(...) |
openmeta/metadata_translation.h |
Experimental | Transactional v1 projection of eligible edited XMP creation dates into exact native EXIF/IPTC date groups. The caller selects mappings, source mode, conflict behavior, and lowered resource limits; lossy precision, malformed dates, duplicate sources, and unresolved conflicts fail without replacing the output. Python exposes the same C++ transaction through a detached Document. See translation.md. |
Reverse technical EXIF translation: translate_xmp_technical_metadata(...) |
openmeta/metadata_translation.h |
Experimental | Transactional v1 projection of exact xmp:ModifyDate, tiff:Make, tiff:Model, and xmp:CreatorTool properties into native EXIF groups. Full ModifyDate precision uses OffsetTime/SubSecTime companions; singleton conflicts, dirty tombstones, ASCII validity, duplicates, and resource limits are explicit. Python remains a thin detached-document wrapper. See translation.md. |
Reverse capture EXIF translation: translate_xmp_capture_metadata(...) |
openmeta/metadata_translation.h |
Experimental | Transactional v1 projection of exposure time, F-number, ISO, focal length, and exposure compensation XMP properties into tag-specific native RATIONAL, SHORT, and SRATIONAL scalars. Exact integer conversion, portable/standard alias ambiguity, dirty tombstones, conflicts, and resource limits are explicit; unrepresentable decimals fail instead of being approximated. Python remains a thin detached-document wrapper. See translation.md. |
Target-bound image-geometry translation: translate_xmp_image_geometry(...) |
openmeta/metadata_translation.h, openmeta/metadata_transfer.h |
Experimental | Transactional v1 projection of exact XMP orientation and complete stored-raster dimensions into canonical native TIFF/EXIF SHORT/LONG groups. Active values must agree with caller-provided TransferTargetImageSpec facts; standard/portable aliases, incomplete pairs, dirty tombstones, conflicts, and limits are explicit. Display-oriented dimensions are never inferred or swapped. Python remains a thin detached-document wrapper. See translation.md. |
Reverse descriptive translation: translate_xmp_descriptive_metadata(...) |
openmeta/metadata_translation.h |
Experimental | Transactional v1 projection of exact default-language title/description/rights, indexed creators/keywords, credit, and source into bounded IPTC-IIM datasets. Repeated cardinality, dirty tombstones, byte limits, conflicts, and UTF-8 charset declaration are explicit; unsafe legacy charset reinterpretation fails atomically. Python remains a thin detached-document wrapper. See translation.md. |
Reverse location translation: translate_xmp_location_metadata(...) |
openmeta/metadata_translation.h |
Experimental | Transactional v1 projection of five flat IPTC Core location properties into native IPTC-IIM. Reuses descriptive policies, statuses, and result diagnostics with separate location options. Exact singleton paths, byte limits, country-code syntax, dirty tombstones, and charset safety are explicit; structured locations and GPS are outside the contract. Python provides the same operation. See translation.md. |
Reverse editorial translation: translate_xmp_editorial_metadata(...) |
openmeta/metadata_translation.h |
Experimental | Transactional v1 Headline, Instructions, and TransmissionReference writeback with independent editorial options. Reuses descriptive policies/results, exact singleton validation, UTF-8 safety, and resource limits. Python provides the same operation. See translation.md. |
Combined IPTC translation: translate_xmp_iptc_metadata(...) |
openmeta/metadata_translation.h |
Experimental | Transactional v1 writeback of 20 text/priority groups, adding creator job title, caption writer, category, supplemental categories, and urgency. Independent flags, shared charset/resource limits, and cross-group atomicity. Existing subgroup/date contracts are unchanged. Python provides the same operation. See translation.md. |
Structured location reconciliation: translate_xmp_structured_location_metadata(...) |
openmeta/metadata_translation.h |
Experimental | Transactional v1 projection of one explicitly selected structured record into five flat XMP/native IPTC pairs. Record kind/index, paired conflicts, dirty leaf removal, text limits, and charset safety are explicit. Python provides the same operation. See translation.md. |
Primary GPS translation: translate_xmp_gps_metadata(...) |
openmeta/metadata_translation.h |
Experimental | Transactional v1 latitude/longitude and altitude/reference writeback. Exact rational precision, paired source/native reconciliation, GPS version handling, and resource limits are explicit. Python provides the same operation. See translation.md. |
GPS time/navigation translation: translate_xmp_gps_navigation_metadata(...) |
openmeta/metadata_translation.h |
Experimental | Transactional v1 UTC date/time, speed/unit, track/reference, and image direction/reference writeback. Exact precision, UTC rollover, version support, paired conflicts/removal, and portable reference aliases are explicit. Python provides the same operation. See translation.md. |
Destination GPS translation: translate_xmp_gps_destination_metadata(...) |
openmeta/metadata_translation.h |
Experimental | Transactional v1 destination coordinates, bearing/reference, and distance/unit writeback. Exact precision, paired conflicts/removal, version retention, and historical distance-label compatibility are explicit. Python provides the same operation. See translation.md. |
GPS quality translation: translate_xmp_gps_quality_metadata(...) |
openmeta/metadata_translation.h |
Experimental | Transactional v1 status, measurement mode, DOP, differential correction, and horizontal error with explicit enum, precision, version, and removal contracts. Python provides the same operation. See translation.md. |
GPS text translation: translate_xmp_gps_text_metadata(...) |
openmeta/metadata_translation.h |
Experimental | Transactional v1 satellites, map datum, processing method, and area with explicit ASCII/Unicode encoding, version, conflict, and removal contracts. Python provides the same operation. See translation.md. |
LightSource translation: translate_xmp_light_source_metadata(...) |
openmeta/metadata_translation.h |
Experimental | One bounded LightSource SHORT with exact code/unique-label selection, ambiguity rejection, typed conflicts and removal. Python provides the same operation. See translation.md. |
Sensitivity translation: translate_xmp_sensitivity_metadata(...) |
openmeta/metadata_translation.h |
Experimental | Seven-tag sensitivity group with explicit companions, LONG limits, whole-group conflicts and atomic removal. Independent options preserve existing capture layouts. Python provides the same operation. See translation.md. |
Camera/lens/spectral text translation: translate_xmp_camera_text_metadata(...) |
openmeta/metadata_translation.h |
Experimental | Six independent printable-ASCII fields in one transaction, with exact namespaces, explicit aliases, typed conflicts, bounds and removal. Python provides the same operation. See translation.md. |
Flash translation: translate_xmp_flash_metadata(...) |
openmeta/metadata_translation.h |
Experimental | Complete scalar or five-child Flash writeback with explicit bitfield, conflict, and removal rules. Python provides the same operation. See translation.md. |
Capture rational translation: translate_xmp_capture_rational_metadata(...) |
openmeta/metadata_translation.h |
Experimental | Four exact unsigned capture rationals with explicit sentinel, precision, conflict, and removal rules. Python provides the same operation. See translation.md. |
Capture settings translation: translate_xmp_capture_settings_metadata(...) |
openmeta/metadata_translation.h |
Experimental | Twelve closed SHORT camera-setting enums with explicit labels, limits, and atomic conflicts/removal. Python provides the same operation. See translation.md. |
Structured location construction: translate_xmp_location_to_structured_metadata(...) |
openmeta/metadata_translation.h |
Experimental | Five flat XMP fields into one explicitly selected Created/Shown record, with dense indexes and atomic leaf conflicts/removal. Python provides the same operation. See translation.md. |
EXIF/TIFF orientation helpers: interpret_exif_orientation(...), exif_orientation_name(...), exif_orientation_rotation_degrees_cw(...), exif_orientation_rotation_only(...) |
openmeta/orientation.h |
Stable | Small utility contract for user-facing orientation labels, clockwise rotation degrees, mirrored-state detection, dimension-swap detection, and rotation-only fallbacks. Python exposes the same helpers through thin scalar/dictionary wrappers. |
EXIF/TIFF/DNG numeric value names and version formatting: exif_tag_numeric_value_name(...), exif_tag_numeric_value_format(...), exif_tag_byte_value_format(...), and focused helpers |
openmeta/exif_value_names.h |
Stable | Small helper contract for common enum-like TIFF/EXIF/DNG numeric values such as compression, photometric interpretation, planar configuration, exposure program/mode, metering mode, light source, flash, color space, white balance, scene capture type, gain control, CFA layout, DNG calibration illuminants, and EXIF 3.1 lens-correction / noise-reduction status values, plus selected bounded Canon/Nikon/Sony/Fujifilm/Pentax/Olympus/Panasonic/Phase One/Kodak/Minolta/Sigma/Samsung/Ricoh/Apple/FLIR/JVC/GE/Reconyx/Microsoft/Motorola/Nintendo/Sanyo MakerNote contexts including NikonSettings On/Off labels, Reconyx scalar labels, Microsoft stitch labels, Motorola CustomRendered labels, Nintendo category labels, Sanyo public-context scalar labels, current Canon RF lens-type labels, current Nikon Z LensData0800 LensID labels, and an ambiguous Pentax Sigma/Samsung/Tokina lens-family label where stable. Version/firmware helpers format selected standard EXIF byte-version fields, Nikon version-like payloads, Olympus packed firmware values, and native RAF firmware payloads without treating formatted versions as enum labels. Unknown or ambiguous values return an empty string or false and remain lossless metadata. |
Photoshop IRB decode: decode_photoshop_irb(...), measure_photoshop_irb(...) |
openmeta/photoshop_irb_decode.h |
Experimental | Bounded resource traversal with stable raw resource preservation behavior, but the interpreted subset can still grow. Current interpretation includes fixed-layout resource fields, display/grid/thumbnail/color-sampler headers, working-path and numbered clipping-path byte counts / record summaries, descriptor-header summaries plus safe descriptor class-name/class-ID/item-count fields, bounded descriptor item bodies for bool, long, comp, doub, UntF, TEXT, enum, type, and GlbC, opaque alis and tdta byte counts, ordered obj property/class/enumerated/offset/identifier/index/name reference fields with per-value and aggregate limits, descriptor item/reference type-name/type-code fields, parsed maximum depth, and parsed per-type counters, nested object/list traversal with item path/depth/list-index and parsed-value count fields, XMLData, ImageReady ASCII text resources, Lightroom workflow text, MacintoshPrintInfo / Macintosh NSPrintInfo / Windows DEVMODE / AlternateDuotoneColors / AlternateSpotColors / obsolete Photoshop tag byte counts, legacy halftone/transfer/duotone/EPS byte summaries, embedded IPTC/ICC/EXIF/EXIF2/XMP byte-count fields, and optional embedded IPTC-IIM, XMP, and ICC payload decode. |
Additional capture and environment translation: translate_xmp_capture_additional_metadata(...), translate_xmp_environment_metadata(...) |
openmeta/metadata_translation.h |
Experimental v1 | Nine typed native fields, explicit aliases/codes/units, exact rationals and raw unknown-denominator preservation. Two bounded transactions with thin Python wrappers. See translation.md. |
Image encoding and composite translation: translate_xmp_image_encoding_metadata(...), translate_xmp_composite_metadata(...) |
openmeta/metadata_translation.h |
Experimental v1 | Six native fields with exact nonnegative rationals, four component codes, complete composite dependencies and bounded exposure lists. Python mirrors both transactions. Raw big-endian exposure bytes use EntryFlags::ValueBigEndian; snapshots carrying this flag require 0.5.7 or later. See translation.md. |
Semantic metadata query: query_metadata(...), query_crop_metadata(...), and focused query helpers |
openmeta/metadata_query.h |
Experimental | Query contract for inspection matches plus normalized candidates. Current coverage includes crop/active-area/border margins, exposure/gain, white balance, color/profile/source-color-transform, lens correction, orientation, descriptive EXIF/IPTC/XMP fields including exact contact/event/person/organization/product/artwork/rights/license/credit/source/rights-expression/release semantics, and RAW/source-processing metadata across standard tags, selected DNG tags, RAW value curves, RAW linearity limits, RAW calibration curves, RAW curve control points, EXIF color-space evidence, ICC header/tag entries, XMP ICC/profile/color-space fields, XMP camera RAW profile/look/tone-curve fields, PNG profile text carriers, Fujifilm RAF raw crop/zoom rectangles, Canon aspect/crop metadata, Canon AF micro-adjustment, Canon ambience-selection, Canon ColorData source color-transform, NikonSettings source-processing aliases, Nikon Capture crop bounds, Sony panorama crop margins, selected decoded vendor/MakerNote exposure names, crop/border XMP paths, and vendor RAW-processing classification. Semantic Query uses deterministic tag, namespace, and name matching; tolerant partial matching is isolated in the separate Fuzzy Search API so near names cannot change metadata meaning. Matches retain exact_match, fuzzy_match, and fuzzy_score compatibility fields. Exact descriptive semantics added after the full legacy 32-bit match-term mask may have zero matched_terms; their explicit semantic and confidence remain authoritative. Grouped candidates include matrix_set, vector_set, and table shapes for related non-crop metadata, including RAW black/white levels, linearization, raw value curves, raw linearity limits, raw calibration curves, raw curve control points, CFA/sensor layout, source geometry, raw-storage identifiers, source-processing buckets, and per-family vendor MakerNote/RAW white-balance, source-color-transform, raw-storage, sensor, computational, thermal, stitch/panorama, and source-processing groups. Matrix/vector/table groups are promoted only when the available numeric payloads meet conservative minimum shapes, so malformed color matrices, white-balance vectors, and lens-correction records remain per-entry inspection data instead of becoming normalized groups. Long-tail source color/style/lens/source-processing aliases such as camera-to-XYZ/RGB matrices, creative/picture style, film simulation, dynamic-range, optical-correction, AF micro-adjustment, ambience selection, Canon ColorData, NikonSettings, and raw-development terms are classified for query and transfer-policy inspection; camera RAW profiles, looks, tone curves, and vendor source color tables use the explicit source_color_transform semantic, RAW curve/linearity metadata uses dedicated RAW-processing semantics, and computational, thermal, and stitch/panorama fields use explicit source-processing subroles. Python Document and TransferSourceSnapshot mirror this as thin dictionary-returning wrappers. |
Bounded fuzzy entry search: fuzzy_search_metadata(...), metadata_fuzzy_search_available() |
openmeta/metadata_fuzzy_search.h |
Experimental | Optional RapidFuzz-backed search over decoded metadata names and property paths. The API has bounded query/candidate/result sizes, caller-selected score cutoff, deterministic top-k ordering, stable entry-id ties, explicit exact/curated-alias/general-fuzzy provenance, and status returns for unavailable, invalid, short, long, or non-ASCII queries. The current normalization contract is locale-independent ASCII with separator, camel-case, and acronym-boundary normalization but without Unicode normalization or transliteration. Calls use local state and are safe against an immutable finalized store. Python Document and TransferSourceSnapshot expose thin dictionary wrappers. |
Structured metadata interpretation records: interpret_metadata(...), interpret_metadata_query(...) |
openmeta/metadata_interpretation.h |
Experimental | Thin structured projection over semantic query candidates. Records carry query class, semantic kind, normalized shape, confidence, source entry ids, and normalized origin/size/rect/margins/value arrays where available. Current scope covers orientation, geometry/crop/border including Fujifilm RAF, Canon, Nikon Capture, and Sony panorama geometry patterns, exposure/gain, color/white-balance/profile/source-color-transform records, lens-correction, RAW/source-processing records including raw value curves, linearity limits, calibration curves, curve control points, computational, thermal, and stitch/panorama subroles, and grouped vendor-family table/vector records where classification supports them. Python Document and TransferSourceSnapshot expose matching dictionary wrappers. |
Cross-family concept resolution: resolve_metadata_concepts(...), resolve_metadata_concept(...) |
openmeta/metadata_concepts.h |
Experimental | First bounded resolver for duplicated host-facing concepts. Current scope reports candidates, candidate source entries, source families, preferred entries, normalized numeric/text keys, full normalized value vectors, transfer hints, RAW applicability states, normalized date/time fields, date/time precision including bounded subsecond digits, timezone kind, normalized geometry fields, normalized exposure values, and same-role conflicts for orientation, date/time, exposure/gain, color/profile/source-color-transform, GPS, descriptive fields, geometry, lens-correction, RAW-processing, and container-graph evidence across EXIF, XMP, IPTC, ICC, PNG text, BMFF fields, and query-backed interpretation records where applicable. Exposure candidates cover exposure time, aperture, ISO sensitivity, exposure bias, exposure program/mode, gain, and raw exposure-adjustment roles across standard EXIF/DNG/XMP evidence and selected decoded vendor/MakerNote exposure names; standard EXIF exposure program/mode and gain-control values plus selected Canon/Nikon/Sony/Fujifilm/Pentax/Olympus/Panasonic/Phase One/Kodak/Minolta/Sigma/Samsung/Ricoh MakerNote values include human-readable labels where stable; capture exposure facts are safe, while raw/DNG exposure adjustments stay rendered-unsafe. Geometry candidates cover crop, active area, border, and sensor geometry with canonical origin, size, rect, and margin fields when available, including normalized DNG, Phase One/Leaf, Fujifilm RAF, Canon, Nikon Capture, and Sony panorama geometry patterns. Candidate transfer hints distinguish safe, source_bound, rendered_unsafe, and requires_target_image_spec evidence, with compatible-file and rendered-image safety booleans. Color/white-balance, source-color-transform, lens-correction, RAW-processing, and container-graph concepts preserve source evidence for host inspection; source-bound color transforms and RAW curve/linearity/calibration roles are marked rendered-unsafe, computational/thermal/stitch RAW-processing roles are marked source-bound, and BMFF whole-scene, primary-component, per-component content-bound metadata / multi-image policy, and derived-image construction fields are marked source-bound. RAW curve/LUT-like concept roles are conservatively marked conditional_on_raw_encoding until a raw data descriptor can confirm whether they affect the stored samples; descriptor-aware overloads accept MetadataRawDataDescriptor and can collapse supported stored-RAW descriptors to applies_to_stored_raw, rendered descriptors to not_applicable_to_stored_raw, compressed-only descriptors to not-applicable when the supplied storage encoding is uncompressed or packed, and primary-plane-only descriptors to not-applicable when the supplied plane index is non-primary. Matching EXIF OffsetTime* and SubSecTime* entries are assembled with DateTime* candidates, offset-aware conflicts compare normalized UTC instants, and missing timezone or subsecond fields remain lower-precision evidence. EXIF and XMP GPS date/time are combined from same-scope GPSDateStamp plus GPSTimeStamp entries, direct XMP GPSDateTime / GPSDateTimeStamp values map to the GPS timestamp role, IPTC digital-creation date/time and XMP DateTimeDigitized map to the Digitized date/time role, and GPS altitude candidates expose altitude-reference code plus below-sea-level state when reference metadata is present. Camera position, EXIF/XMP destination coordinates, and IPTC Extension LocationShown / LocationCreated coordinates use distinct roles. Structured candidates expose location_scope, and conflict/preference handling compares values only within the same scope; metadata_concept_gps_altitude_reference_name(...) provides a stable display token for altitude reference codes. The Descriptive kind reconciles standard title, headline, description, creator, keyword/subject, created/shown location, copyright, rights/license, credit, and source fields. Localized scalars compare per normalized language; creator, keyword, location-identifier, rights-holder, and licensor collections preserve distinct values and select one preferred source per duplicate normalized value. Structured PLUS owner/licensor members expose record_scope so related names and identifiers remain associated. It is intended for inspection UI and host policy decisions; it does not rewrite metadata or hide ambiguity. Python Document and TransferSourceSnapshot expose matching dictionary wrappers, including subsecond, location-scope, record-scope, and language fields and the thin MetadataRawDataDescriptor object with storage, compression, and plane-binding fields. |
Transfer concept diagnostics: transfer_concept_diagnostics_from_store(...), transfer_concept_diagnostic_message(...), transfer_concept_diagnostic_token(...), transfer_concept_diagnostic_message_token(...), transfer_concept_diagnostic_message_arguments(...) |
openmeta/metadata_transfer.h |
Experimental | Preflight view over concept candidates for TransferSafetyMode. Each diagnostic reports concept kind/role, transfer hint, keep/drop/requires-target-image-spec action, reason token, severity token, stable host-facing summary token, stable localization message token, localizable argument tokens, default message text, conflict flag, source entries, structured-location scope, generic structured-record scope, and language where applicable, compatible/rendered safety booleans, RAW applicability state, and GPS altitude-reference presentation fields. Descriptor-aware overloads accept MetadataRawDataDescriptor and make RAW-processing keep/drop decisions reflect the supplied stored-RAW, compressed-only, primary-plane-only, or rendered storage context. PrepareTransferRequest::source_raw_data_descriptor can apply the same coarse rendered-source RAW filtering during prepare_metadata_for_target(...); it is still intentionally conservative and does not prove vendor curve/LUT activity for a specific compression mode or decoder stage. Rendered-transfer drop messages distinguish source color transforms, white balance, lens-correction records, source RAW curves/linearity metadata that still require storage-context confirmation, computational/thermal/stitch source-processing drops, and BMFF container-graph content-bound metadata / multi-image scene / derived-image construction drops from generic source-processing metadata. Python Document and TransferSourceSnapshot expose transfer_concept_diagnostics(...) dictionaries with severity_name, token, message_token, message_arguments, message, location_scope, record_scope, language, and RAW applicability fields, with overloads that accept the thin MetadataRawDataDescriptor object; Python transfer helpers also accept source_raw_data_descriptor for prepare-time filtering. |
Vendor RAW-processing summaries: vendor_raw_processing_from_store(...), classify_vendor_raw_processing_field(...) |
openmeta/vendor_raw_processing.h |
Experimental | Conservative grouped source-RAW/source-processing field summaries for decoded Sony, Canon, Nikon, Fujifilm, Pentax, Panasonic, Olympus, Kodak, Minolta, Sigma, Samsung, Ricoh, Apple, DJI, Google, FLIR, Casio, Sanyo, KyoceraRaw, Reconyx, HP, JVC, GE, Motorola, Nintendo, and Microsoft MakerNotes, including vendor-private, computational, thermal, preview, face-geometry, stitch/panorama, Apple computational capture/HDR/motion, DJI pose/thermal, Google HDR+/shot-log, pixel-shift/multi-shot/composite/auto-lighting/source-style processing, and FLIR radiometric/raw-value buckets. Long-tail aliases cover source color/style, camera-to-XYZ/RGB matrix, white-balance gain, optical/lens correction, dynamic-range, and raw-development terms. Direct field classification also recognizes decoded Phase One/Leaf RAW-processing tags; use the dedicated Phase One/Leaf helpers for normalized geometry and processing summaries. Intended for audit/UI and rendered-transfer safety decisions, not for writing vendor RAW/source-processing values into rendered targets. |
Transfer safety audit: transfer_safety_audit_from_store(...) |
openmeta/metadata_transfer.h |
Experimental | Preflight summary of source entries and entries filtered or invalidated by TransferSafetyMode, including Sony/Canon/Nikon/Fujifilm/Pentax/Panasonic/Olympus/Kodak/Minolta/Sigma/Samsung/Ricoh/Apple/DJI/Google/FLIR/Casio/Sanyo/KyoceraRaw/Reconyx/HP/JVC/GE/Motorola/Nintendo/Microsoft RAW/source-processing buckets. Intended for diagnostics and host UI before preparing rendered-image transfers. |
MakerNote transfer audits: makernote_transfer_audit_from_store(...), makernote_layout_transfer_audit_from_store(...) |
openmeta/metadata_transfer.h |
Experimental | The generic audit reports raw opaque payload and decoded-only entry counts plus current rewrite trust capabilities. The layout audit recognizes canonical Nikon type 1 outer-TIFF-relative notes and type 3 notes with an embedded TIFF at byte 10; bounded embedded-TIFF validation covers standard directory/value offsets only. It also recognizes plausible Canon source-dependent IFD notes when the EXIF camera make is Canon, but reports their source offset basis as ambiguous and does not mark them rewritable. The writer still cannot reconstruct decoded fields, relocate vendor-private offsets, repair checksums, prove semantic readability, or pass MakerNotes through as raw carriers. Python Document and TransferSourceSnapshot expose matching thin dictionary wrappers. |
Raw-carrier passthrough audit: raw_carrier_passthrough_audit_from_snapshot(...) |
openmeta/metadata_transfer.h |
Experimental | Diagnostic preflight for opt-in raw carriers. Reports candidate carriers and primary block reasons such as missing payload, target incompatibility, safety filtering, content-bound C2PA, explicit profile policy, missing decoded-entry links, or unsupported carrier kind. Hosts can call it directly before enabling snapshot passthrough. |
Decoded source snapshot state: TransferSourceSnapshot |
openmeta/metadata_transfer.h |
Stable v1 profile | Stable decoded-store state for positional read, persistence, and reconciliation. Optional raw-carrier records are preserved as data, but raw-carrier passthrough policy remains experimental. Const reuse is safe when callers do not mutate the snapshot. |
File/bytes/build snapshot helpers: read_transfer_source_snapshot_file(...), read_transfer_source_snapshot_bytes(...), build_transfer_source_snapshot(...) |
openmeta/metadata_transfer.h |
Experimental | Convenience entry points outside the narrow positional Host Adoption Profile. |
Versioned source snapshot persistence: serialize_transfer_source_snapshot(...), deserialize_transfer_source_snapshot(...) |
openmeta/metadata_transfer.h |
Stable v1 | Target-neutral canonical v1 representation with transactional bounded parsing and an exact compatibility vector. Preserves store blocks, ordered duplicate entries, typed values, provenance, tombstones, flags, and optional raw-carrier links. Current readers accept v1 and reject unknown versions atomically; persistence does not imply that raw bytes are safe to relocate or rewrite. |
Fileless preparation: prepare_metadata_for_target_snapshot(...) |
openmeta/metadata_transfer.h |
Experimental | Intended for hosts that already decoded metadata and want to prepare transfer artifacts without reopening the source file. TransferRawCarrierPassthroughMode::WhenSafe is an opt-in snapshot mode; the current writer path only reuses eligible non-C2PA JUMBF and draft unsigned C2PA invalidation carriers for JPEG, JXL, and BMFF targets, plus draft unsigned C2PA invalidation carriers for WebP. |
Snapshot execution: execute_prepared_transfer_snapshot(...) |
openmeta/metadata_transfer.h |
Experimental | Intended for deferred save/writeback from a reusable decoded source snapshot. |
Bundle execution: execute_prepared_transfer_bundle(...) |
openmeta/metadata_transfer.h |
Experimental | Intended for hosts that already own a prepared bundle and destination bytes. Treat bundles as immutable except through documented patch helpers. |
Typed adapter operation schema: PreparedTransferAdapterOp, TransferAdapterOpKind, kPreparedTransferAdapterContractVersion |
openmeta/metadata_transfer.h |
Stable v1 schema | Enum-based insertion operations for JPEG, TIFF/DNG, JXL, WebP, PNG, JP2, EXR, and BMFF. Marker/tag/box/chunk/item/property fields are explicit. Stable hosts obtain payload and EXR name/type/value views through PreparedTransferHandoff; codecs do not parse route strings. |
Adapter-view build, validation, and execution: build_prepared_transfer_adapter_view(...), validate_prepared_transfer_adapter_view(...), emit_prepared_transfer_adapter_view(...) |
openmeta/metadata_transfer.h |
Experimental | Builds and validates the stable v1 operation schema over an experimental prepared bundle. Validation compares every operation with the canonical compiled view before codec handoff. |
Persisted prepared payload/package batches: serialize_prepared_transfer_payload_batch(...), deserialize_prepared_transfer_payload_batch(...), serialize_prepared_transfer_package_batch(...), deserialize_prepared_transfer_package_batch(...), replay and view helpers |
openmeta/metadata_transfer.h |
Experimental | Owned target-specific encoder/package handoff. The current wire formats are versioned and bounded, but route and operation details have not yet graduated to a stable compatibility contract. |
| Generated transfer payload internals, undocumented route strings, low-level package chunks, and diagnostic counters not covered by a host-facing API row | openmeta/metadata_transfer.h |
Internal | These fields may be useful for tests and diagnostics, but they are not a compatibility contract for downstream integrations. |
Structured descriptive candidates now expose experimental record_kind,
record_scope, and sensitivity fields. Record kinds cover creator contacts,
events, people, organizations, products, artwork/objects, rights expressions,
rights holders, licensors, licensees, licenses, releases, end users, image
creators, image suppliers, image assets, controlled-vocabulary terms, registry
entries, image regions, resource references, resource events, manifest items,
versions, editorial workflows, source software, editorial contacts, and pantry
items, plus legacy IPTC technical-image, audio-asset, and preview-asset
records. The IPTC technical records normalize image layout, component count,
audio channel/rate/resolution/duration, preview format/version, and bounded
binary payload identity without treating IPTC layout as EXIF rotation.
Sensitivity is a
policy signal independent of technical transfer safety; the same fields are
mirrored in transfer diagnostics and thin Python dictionaries. Hosts must not
interpret safe as approval to publish personal-contact, person-identity,
location, or legal-rights metadata.
Exact descriptive query semantics also cover legacy editorial workflow pairs,
non-equivalent IPTC taxonomy and workflow fields, scoped prior-envelope
references and originating software, IPTC Core accessibility and taxonomy
fields, IPTC Extension registry and
image-region entities, resource/document identity and lineage/history, and
remaining bounded PLUS party, delivered-asset, and license-policy fields.
Legacy IPTC image, audio, and preview datasets use exact technical_image,
audio, and preview semantics.
Equivalent scalar pairs participate in preference/conflict handling; taxonomy,
resource-identifier, and license-document collections remain additive.
Document identity/lineage/history, registry, prior-envelope-reference, and
source-software records are source-bound for rendered transfer; image-region
records require target image specifications. Editorial contacts carry
personal-contact sensitivity independently of their technical transfer hint.
Technical-image, audio-asset, and preview-asset records are source-bound.
The bounded BMFF tiled-image field contract covers tilC version 0 tile
dimensions, up to eight extra dimensions, dref/deti mapping, internal
tile_item_type/tipa associations, bounded external URL components, logical
offset-table rows, explicit or sequentially inferred tile sizes, and separate
core/layout/complete validity. Offset-table validation is capped at 262144
entries, emitted rows at 64, property associations at 64, and retained URL
components at 512 bytes. TiledImageConfiguration remains an experimental
source-bound concept role exposed unchanged by the thin Python enum.
Use stable APIs for normal application integrations. Use experimental APIs when they match a real workflow and the integration can track OpenMeta releases. Avoid internal surfaces unless you are contributing to OpenMeta itself or writing a test that is intentionally tied to implementation details.
High-throughput hosts should use Host Adoption Profile v1 for read/state compatibility and Prepared Transfer Handoff v1 for stable target preparation, then query format capabilities separately.
The 0.5.8 structured capture batch adds OECF, SpatialFrequencyResponse,
CFAPattern and DeviceSettingDescription through
translate_xmp_structured_capture_metadata and its Python counterpart.
The 0.5.8 combined inventory was 65 distinct native tags across fifteen APIs
(62 retained by compatible-file transfer). ABI 3 and host synchronization
remain unchanged; big-endian snapshots for the four new fields need a 0.5.8
reader. See Structured capture data.
The 0.5.9 text/version batch adds UserComment, both version fields and seven EXIF 3 text tags. The new EXIF text API also supports UTF-8 owner/lens fields. The combined capture inventory is 75 distinct ExifIFD tags across sixteen APIs; compatible-file transfer retains 72. Version and Artist/Software companion requirements are explicit. ABI 3, snapshot v1 layout and host synchronization responsibilities remain unchanged. BOM-less big-endian UserComment snapshots require a 0.5.9 reader. See the EXIF text/version translation contract for limits and the recorded OIIO/ExifTool reader limitations.
The 64 previously unrecognized capture/date/GPS reverse targets now have fixed schemas. Five Interop fields and three structural pointers are also recognized. Malformed known field types, counts and covered values can now fail default authoring, typed editing and canonical serialization. Valid InteroperabilityIndex is accepted despite its numeric ID overlap with GPS. Portable output preserves eligible existing XMP when the corresponding native value fails shared checks.
Public signatures, contract versions, ABI 3, snapshot v1 layout and host-owned synchronization remain unchanged. No mandatory complete-file profile is imposed. See generic validation for scope and limits.