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 |
|---|---|---|---|
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. |
Compatibility dumps: dump_metadata_compatibility(...), dump_transfer_compatibility(...) |
openmeta/compatibility_dump.h |
Stable | Stable v1 line-oriented compatibility dump contract. 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. |
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: exif_tag_numeric_value_name(...) 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, metering mode, light source, flash, color space, white balance, scene capture type, gain control, CFA layout, and DNG calibration illuminants. Unknown values return an empty string and remain lossless numeric metadata. |
Semantic metadata query: query_metadata(...), query_crop_metadata(...), focused query helpers, and metadata_query_fuzzy_search_available() |
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, lens correction, orientation, and RAW/source-processing metadata across standard tags, selected DNG tags, fuzzy XMP paths, and vendor RAW-processing classification. Matches report exact_match, fuzzy_match, and fuzzy_score so tools can label exact results separately from RapidFuzz near-miss hits. OPENMETA_ENABLE_RAPIDFUZZ=ON adds optional near-miss XMP/property-path scoring. Grouped candidates include matrix_set, vector_set, and table shapes for related non-crop metadata, including RAW black/white levels, linearization, CFA/sensor layout, source geometry, raw-storage identifiers, and source-processing buckets. Python Document and TransferSourceSnapshot mirror this as thin dictionary-returning 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, exposure/gain, color/white-balance, lens-correction, and RAW/source-processing records. 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, normalized date/time fields, and same-role conflicts for orientation, date/time, color/profile, and GPS evidence across EXIF, XMP, IPTC, ICC, and PNG text where applicable. GPS date/time is combined from GPSDateStamp plus GPSTimeStamp when both entries exist. 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. |
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, and FLIR radiometric/raw-value buckets. 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. |
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. |
Source snapshot type and read helpers: TransferSourceSnapshot, read_transfer_source_snapshot_file(...), read_transfer_source_snapshot_bytes(...), build_transfer_source_snapshot(...) |
openmeta/metadata_transfer.h |
Experimental | Current snapshots are decoded-store-backed by default. Opt-in raw carriers preserve bounded source payload/provenance records and snapshot-local decoded entry ids for host diagnostics and bounded passthrough decisions. Const reuse is safe when callers do not mutate the snapshot and do not share returned result objects across writers. |
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. |
Adapter-view execution: build_prepared_transfer_adapter_view(...), emit_prepared_transfer_adapter_view(...) |
openmeta/metadata_transfer.h |
Experimental | Target-neutral operation view for host-owned encoders and writers. Route and dispatch details may still evolve. |
| Generated transfer payload internals, route strings, low-level package chunks, and diagnostic counters not documented by a stable API page | openmeta/metadata_transfer.h |
Internal | These fields may be useful for tests and diagnostics, but they are not a compatibility contract for downstream integrations. |
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.