Add descriptive metadata query

ssh4net · ssh4net · commit ba4c0417538d · 2026-05-21T16:21:08.000+09:00
Introduce a Descriptive MetadataQueryKind with semantic kinds (Title, Description, Creator, Keywords) and corresponding match-term bits, plus the query_descriptive_metadata API. Add EXIF/IPTC/XMP tag constants and matching helpers (exact and fuzzy term matching, XMP leaf extraction, IPTC dataset mapping) to reconcile common descriptive fields across EXIF/IPTC/XMP (title/headline, description/caption, creator/author, keywords/subject). Wire descriptive candidates into interpretation output and query dispatch, update kind/semantic name strings, and add unit tests covering EXIF/IPTC/XMP reconciliation. Update docs and CHANGES, and bump VERSION to 0.4.21.
diff --git a/CHANGES.md b/CHANGES.md
@@ -1,5 +1,17 @@
 # OpenMeta Changes
 
+## 0.4.21 - 2026-05-21
+
+Changes compared with `0.4.20`.
+
+### Added
+
+- Added `query_descriptive_metadata(...)` for bounded descriptive
+  EXIF/IPTC/XMP reconciliation across title/headline,
+  description/caption, creator/author, and keywords/subject metadata.
+- Structured interpretation now includes descriptive query records, preserving
+  source entry provenance for UI and host reconciliation workflows.
+
 ## 0.4.20 - 2026-05-21
 
 Changes compared with `0.4.19`.
diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-0.4.20
+0.4.21
diff --git a/docs/interpretation_status.md b/docs/interpretation_status.md
@@ -32,7 +32,7 @@ explicit outcome:
 | --- | --- | --- | --- |
 | Standard EXIF/TIFF/DNG tag names and typed values | Standard tag names, common scalar/vector values, DNG crop/color/exposure/RAW-processing fields, GeoTIFF key names, and common EXIF/TIFF/DNG numeric value-name helpers are available. Exposure time, aperture, ISO sensitivity, exposure bias, exposure program, gain, and raw exposure-adjustment records now flow into concept candidates. | High, about 91-95%. | More enum-style human-readable values and richer conflict handling between duplicated families. |
 | ICC profiles | ICC header/tag table decode plus interpreted `desc`, text, signatures, XYZ, curves, named-color, measurement, viewing-condition, MFT/MAB/MBA, numeric array, and malformed/limit handling. | High, about 90-95%. | Full color-management policy remains host-owned; OpenMeta interprets profile metadata, not rendered color transforms. |
-| IPTC-IIM and portable XMP | IPTC datasets and XMP properties decode into typed entries, and bounded EXIF/IPTC-to-XMP projection exists for transfer/writeback. | Medium-high, about 75-85%. | Full MWG-style reconciliation of duplicated EXIF/XMP/IPTC concepts is still bounded. |
+| IPTC-IIM and portable XMP | IPTC datasets and XMP properties decode into typed entries, bounded EXIF/IPTC-to-XMP projection exists for transfer/writeback, and common descriptive EXIF/IPTC/XMP concepts such as title/headline, description/caption, creator/author, and keywords/subject are queryable with source-entry provenance. | Medium-high, about 78-86%. | Full MWG-style reconciliation of duplicated EXIF/XMP/IPTC concepts remains bounded. |
 | Orientation | EXIF/TIFF orientation query, LibRaw flip mapping, generic orientation helpers for index, rotation degrees, mirrored state, dimension swap, rotation-only fallback, human-readable labels, and EXIF-vs-XMP conflict reporting in the LibRaw bridge. | High, about 90-95%. | Higher-level policy for resolving container and host pixel-orientation state remains host-specific. |
 | Geometry, crop, active area, and borders | DNG crop/active-area/masked-area tags, Phase One/Leaf geometry, Fujifilm RAF raw crop/zoom rectangles, Canon aspect/crop metadata, Nikon Capture crop bounds, Sony panorama crop margins, canonical border margins, vendor RAW-processing geometry buckets, and fuzzy crop/border-style paths are queryable. | High, about 88-92%. | More vendor-specific normalized rectangles and stronger output contracts for ambiguous multi-tag geometry. |
 | Exposure and gain | Standard EXIF exposure time, f-number, exposure program, photographic sensitivity, exposure bias, exposure index, gain control, selected DNG baseline/raw-preview gain fields, matching XMP paths, and selected decoded vendor/MakerNote exposure names are queryable and promoted into cross-family exposure roles. Standard EXIF exposure program and gain-control values carry human-readable labels in concept candidates. Capture exposure facts are marked safe, while raw/DNG exposure adjustments are marked unsafe for rendered-image transfer. | Medium-high, about 87-91%. | More vendor MakerNote exposure print conversions and richer per-vendor exposure/gain labels. |
@@ -41,7 +41,7 @@ explicit outcome:
 | Vendor MakerNotes | Broad MakerNote naming and source-processing classification exists for common vendors and several live computational/thermal vendors. Unknown entries remain lossless and source-private subgroups distinguish preview, face geometry, computational, thermal, stitch/panorama, pixel-shift, multi-shot, composite, auto-lighting, RAW crop/active-area, source color-transform, source style/rendering aliases, lens-correction, raw-level processing data, and Phase One/Leaf RAW-processing fields handled by direct classification plus dedicated normalized helpers. Classified multi-field vendor groups now surface as grouped query/interpretation candidates where safe to expose structurally. | Medium-high, about 83-90%. | ExifTool-style long-tail print conversions, encrypted/custom settings, and per-model private tables. |
 | BMFF item graph, HEIF/AVIF/CR3, JUMBF, and C2PA | BMFF derived fields, item-info rows, bounded relations, primary-linked roles, aux semantics, and draft C2PA/JUMBF structural fields are exposed. | Medium, about 60-70%. | Full BMFF scene modeling and full C2PA manifest/policy semantics. |
 | Photoshop IRB | Raw resources are preserved and a bounded interpreted subset is decoded for fixed-layout resources. | Medium, about 60-70%. | Broader resource-specific interpretation. |
-| Semantic query/search and records | Query helpers expose raw matches, confidence, provenance, value shapes, normalized candidates, canonical crop/active-area rectangles, Fujifilm RAF raw crop/zoom rectangles, Canon/Nikon/Sony crop and border patterns, border margins, exposure/gain roles, selected vendor/MakerNote exposure-name aliases, per-family grouped vendor records, expanded source color/style/lens/source-processing aliases, source-processing buckets, optional RapidFuzz near-miss matching, structured interpretation records, and bounded cross-family concept resolution for orientation, date/time, exposure/gain, color/profile, GPS, geometry, lens-correction, and RAW-processing with parsed date/time fields, timezone/precision classification, combined GPS timestamps, GPS altitude-reference state and display token, canonical geometry origin/size/rect/margins, normalized exposure values, shape-checked grouped value vectors, transfer hints, rendered/compatible safety booleans, and tolerance-aware GPS/exposure/color/geometry conflicts. | Medium-high, about 78-84%. | More long-tail per-model concept aliases and richer localized policy wording. |
+| Semantic query/search and records | Query helpers expose raw matches, confidence, provenance, value shapes, normalized candidates, canonical crop/active-area rectangles, Fujifilm RAF raw crop/zoom rectangles, Canon/Nikon/Sony crop and border patterns, border margins, exposure/gain roles, selected vendor/MakerNote exposure-name aliases, per-family grouped vendor records, descriptive EXIF/IPTC/XMP concepts, expanded source color/style/lens/source-processing aliases, source-processing buckets, optional RapidFuzz near-miss matching, structured interpretation records, and bounded cross-family concept resolution for orientation, date/time, exposure/gain, color/profile, GPS, geometry, lens-correction, and RAW-processing with parsed date/time fields, timezone/precision classification, combined GPS timestamps, GPS altitude-reference state and display token, canonical geometry origin/size/rect/margins, normalized exposure values, shape-checked grouped value vectors, transfer hints, rendered/compatible safety booleans, and tolerance-aware GPS/exposure/color/geometry conflicts. | Medium-high, about 79-85%. | More long-tail per-model concept aliases and richer localized policy wording. |
 | Transfer-safety classification | Compatible-file versus rendered-image safety policies classify source-specific image geometry, color/profile, RAW-processing, MakerNote, JUMBF/C2PA, and vendor-private data, with concept-level diagnostics that report keep/drop/requires-target-image-spec actions, severity, and role-specific default message text before prepare. | High, about 89-93%. | More per-family policy tests and optional host localization hooks. |
 
 ## Competitor Position
diff --git a/docs/quick_start.md b/docs/quick_start.md
@@ -145,7 +145,10 @@ Use exact keys for:
 For semantic inspection UI, use `openmeta/metadata_query.h`. It reports raw
 matches plus normalized candidates for areas such as crop/active-area,
 exposure/gain, white balance, color, lens correction, orientation, and
-RAW-processing metadata. These helpers use deterministic built-in name/tag
+RAW-processing metadata. `query_descriptive_metadata(...)` also exposes a
+bounded EXIF/IPTC/XMP reconciliation view for common descriptive fields:
+title/headline, description/caption, creator/author, and keywords/subject.
+These helpers use deterministic built-in name/tag
 matching by default. If OpenMeta is configured with
 `-DOPENMETA_ENABLE_RAPIDFUZZ=ON`, the same query helpers also use RapidFuzz to
 match near-miss property names such as misspelled crop/border/padding paths.
diff --git a/docs/sphinx/interpretation_status.rst b/docs/sphinx/interpretation_status.rst
@@ -80,11 +80,14 @@ Coverage matrix
      - Full color-management policy remains host-owned; OpenMeta interprets
        profile metadata, not rendered color transforms.
    * - IPTC-IIM and portable XMP
-     - IPTC datasets and XMP properties decode into typed entries, and bounded
-       EXIF/IPTC-to-XMP projection exists for transfer/writeback.
-     - Medium-high, about 75-85%.
-     - Full MWG-style reconciliation of duplicated EXIF/XMP/IPTC concepts is
-       still bounded.
+     - IPTC datasets and XMP properties decode into typed entries, bounded
+       EXIF/IPTC-to-XMP projection exists for transfer/writeback, and common
+       descriptive EXIF/IPTC/XMP concepts such as title/headline,
+       description/caption, creator/author, and keywords/subject are queryable
+       with source-entry provenance.
+     - Medium-high, about 78-86%.
+     - Full MWG-style reconciliation of duplicated EXIF/XMP/IPTC concepts
+       remains bounded.
    * - Orientation
      - EXIF/TIFF orientation query, LibRaw flip mapping, and generic
        orientation helpers for index, rotation degrees, mirrored state,
@@ -166,8 +169,9 @@ Coverage matrix
        RAF raw crop/zoom rectangles, Canon/Nikon/Sony crop and border
        patterns, border margins, exposure/gain roles, selected
        vendor/MakerNote exposure-name aliases, per-family grouped vendor
-       records, expanded source color/style/lens/source-processing aliases,
-       source-processing buckets, optional RapidFuzz near-miss matching,
+       records, descriptive EXIF/IPTC/XMP concepts, expanded source
+       color/style/lens/source-processing aliases, source-processing buckets,
+       optional RapidFuzz near-miss matching,
        structured interpretation records, and bounded cross-family concept
        resolution for orientation, date/time, exposure/gain,
        color/profile, GPS, geometry, lens-correction, and RAW-processing with
@@ -177,7 +181,7 @@ Coverage matrix
        origin/size/rect/margins, normalized exposure values, shape-checked
        grouped value vectors, transfer hints, rendered/compatible safety
        booleans, and tolerance-aware GPS/exposure/color/geometry conflicts.
-     - Medium-high, about 78-84%.
+     - Medium-high, about 79-85%.
      - More long-tail per-model concept aliases and richer localized policy
        wording.
    * - Transfer-safety classification
diff --git a/docs/sphinx/quick_start.rst b/docs/sphinx/quick_start.rst
@@ -123,7 +123,10 @@ the metadata family and key:
 For semantic inspection UI, use ``openmeta/metadata_query.h``. It reports raw
 matches plus normalized candidates for areas such as crop/active-area,
 exposure/gain, white balance, color, lens correction, orientation, and
-RAW-processing metadata. These helpers use deterministic built-in name/tag
+RAW-processing metadata. ``query_descriptive_metadata(...)`` also exposes a
+bounded EXIF/IPTC/XMP reconciliation view for common descriptive fields:
+title/headline, description/caption, creator/author, and keywords/subject.
+These helpers use deterministic built-in name/tag
 matching by default. If OpenMeta is configured with
 ``-DOPENMETA_ENABLE_RAPIDFUZZ=ON``, the same query helpers also use RapidFuzz to
 match near-miss property names such as misspelled crop/border/padding paths.
diff --git a/src/include/openmeta/metadata_query.h b/src/include/openmeta/metadata_query.h
@@ -24,6 +24,7 @@ enum class MetadataQueryKind : uint8_t {
     LensCorrection,
     Orientation,
     RawProcessing,
+    Descriptive,
 };
 
 enum class MetadataQuerySemanticKind : uint8_t {
@@ -46,6 +47,10 @@ enum class MetadataQuerySemanticKind : uint8_t {
     SensorGeometry,
     RawStorage,
     SourceProcessing,
+    Title,
+    Description,
+    Creator,
+    Keywords,
 };
 
 enum class MetadataQueryValueShape : uint8_t {
@@ -94,6 +99,10 @@ enum class MetadataQueryMatchTerm : uint32_t {
     Raw              = 1U << 25U,
     Storage          = 1U << 26U,
     SourceProcessing = 1U << 27U,
+    Title            = 1U << 28U,
+    Description      = 1U << 29U,
+    Creator          = 1U << 30U,
+    Keywords         = 1U << 31U,
 };
 
 struct MetadataQueryMatch final {
@@ -165,6 +174,9 @@ query_orientation_metadata(const MetaStore& store);
 MetadataQueryResult
 query_raw_processing_metadata(const MetaStore& store);
 
+MetadataQueryResult
+query_descriptive_metadata(const MetaStore& store);
+
 bool
 metadata_query_fuzzy_search_available() noexcept;
 
diff --git a/src/openmeta/metadata_concepts.cc b/src/openmeta/metadata_concepts.cc
@@ -1867,7 +1867,11 @@ namespace {
         case MetadataQuerySemanticKind::CfaLayout:
         case MetadataQuerySemanticKind::SensorGeometry:
         case MetadataQuerySemanticKind::RawStorage:
-        case MetadataQuerySemanticKind::SourceProcessing: break;
+        case MetadataQuerySemanticKind::SourceProcessing:
+        case MetadataQuerySemanticKind::Title:
+        case MetadataQuerySemanticKind::Description:
+        case MetadataQuerySemanticKind::Creator:
+        case MetadataQuerySemanticKind::Keywords: break;
         }
         return MetadataConceptRole::Primary;
     }
@@ -1986,7 +1990,11 @@ namespace {
         case MetadataQuerySemanticKind::CfaLayout:
         case MetadataQuerySemanticKind::SensorGeometry:
         case MetadataQuerySemanticKind::RawStorage:
-        case MetadataQuerySemanticKind::SourceProcessing: break;
+        case MetadataQuerySemanticKind::SourceProcessing:
+        case MetadataQuerySemanticKind::Title:
+        case MetadataQuerySemanticKind::Description:
+        case MetadataQuerySemanticKind::Creator:
+        case MetadataQuerySemanticKind::Keywords: break;
         }
         return MetadataConceptRole::Primary;
     }
@@ -2029,7 +2037,11 @@ namespace {
         case MetadataQuerySemanticKind::ColorMatrix:
         case MetadataQuerySemanticKind::LensCorrection:
         case MetadataQuerySemanticKind::Orientation:
-        case MetadataQuerySemanticKind::ExposureGain: break;
+        case MetadataQuerySemanticKind::ExposureGain:
+        case MetadataQuerySemanticKind::Title:
+        case MetadataQuerySemanticKind::Description:
+        case MetadataQuerySemanticKind::Creator:
+        case MetadataQuerySemanticKind::Keywords: break;
         }
         return MetadataConceptRole::Primary;
     }
@@ -2255,7 +2267,11 @@ namespace {
         case MetadataQuerySemanticKind::Linearization:
         case MetadataQuerySemanticKind::CfaLayout:
         case MetadataQuerySemanticKind::RawStorage:
-        case MetadataQuerySemanticKind::SourceProcessing: break;
+        case MetadataQuerySemanticKind::SourceProcessing:
+        case MetadataQuerySemanticKind::Title:
+        case MetadataQuerySemanticKind::Description:
+        case MetadataQuerySemanticKind::Creator:
+        case MetadataQuerySemanticKind::Keywords: break;
         }
         return MetadataConceptRole::Primary;
     }
diff --git a/src/openmeta/metadata_interpretation.cc b/src/openmeta/metadata_interpretation.cc
@@ -111,6 +111,7 @@ interpret_metadata(const MetaStore& store)
     append_kind_records(store, MetadataQueryKind::Color, &out);
     append_kind_records(store, MetadataQueryKind::LensCorrection, &out);
     append_kind_records(store, MetadataQueryKind::RawProcessing, &out);
+    append_kind_records(store, MetadataQueryKind::Descriptive, &out);
     return out;
 }
 
diff --git a/src/openmeta/metadata_query.cc b/src/openmeta/metadata_query.cc
diff --git a/tests/metadata_interpretation_test.cc b/tests/metadata_interpretation_test.cc
diff --git a/tests/metadata_query_test.cc b/tests/metadata_query_test.cc

Original file line number	Diff line number	Diff line change
`@@ -111,6 +111,7 @@ interpret_metadata(const MetaStore& store)`
`111`	`111`	`append_kind_records(store, MetadataQueryKind::Color, &out);`
`112`	`112`	`append_kind_records(store, MetadataQueryKind::LensCorrection, &out);`
`113`	`113`	`append_kind_records(store, MetadataQueryKind::RawProcessing, &out);`
	`114`	`+ append_kind_records(store, MetadataQueryKind::Descriptive, &out);`
`114`	`115`	`return out;`
`115`	`116`	`}`
`116`	`117`