Metadata Creation

openmeta/metadata_creation.h is the first high-level Creation contract for fresh metadata. A host supplies logical fields instead of wire tag IDs or XMP namespace paths. OpenMeta validates the complete request and returns a finalized MetaStore containing canonical portable-XMP entries.

The API is experimental and versioned by kMetadataCreationContractVersion == 1.

C++ example

#include "openmeta/metadata_creation.h"

#include <array>

const std::array fields = {
    openmeta::make_metadata_creation_text(
        openmeta::MetadataCreationFieldKind::Title, "Evening frame"),
    openmeta::make_metadata_creation_text(
        openmeta::MetadataCreationFieldKind::Creator, "Alice"),
    openmeta::make_metadata_creation_text(
        openmeta::MetadataCreationFieldKind::Keyword, "night"),
    openmeta::make_metadata_creation_u32(
        openmeta::MetadataCreationFieldKind::Orientation, 6),
    openmeta::make_metadata_creation_urational(
        openmeta::MetadataCreationFieldKind::ExposureTime, 1, 125),
};

openmeta::MetadataCreationRequest request;
request.fields = fields;

openmeta::MetaStore store;
const openmeta::MetadataCreationResult result =
    openmeta::create_metadata(request, &store);

The call is transactional. The output is replaced only after every field passes validation and the new store is finalized. An empty request creates an empty finalized store.

Current mapping

Logical field	Input type	Portable-XMP property	Constraint
Title	Text	dc:title[x-default]	Singleton
Description	Text	dc:description[x-default]	Singleton
Creator	Text	dc:creator[n]	Additive ordered sequence
Keyword	Text	dc:subject[n]	Additive bag
Copyright	Text	dc:rights[x-default]	Singleton
RightsUsageTerms	Text	xmpRights:UsageTerms[x-default]	Singleton
Credit / Source	Text	photoshop:Credit / photoshop:Source	Singleton
CreateDate / ModifyDate	Text	xmp:CreateDate / xmp:ModifyDate	Caller supplies XMP date syntax
Rating	Signed integer	xmp:Rating	-1..5
Label	Text	xmp:Label	Singleton
CameraMake / CameraModel	Text	tiff:Make / tiff:Model	Singleton
Software	Text	xmp:CreatorTool	Singleton
DateTimeOriginal	Text	exif:DateTimeOriginal	Caller supplies XMP date syntax
Orientation	Unsigned integer	tiff:Orientation	EXIF index 1..8
PixelWidth / PixelHeight	Unsigned integer	exif:ExifImageWidth / exif:ExifImageHeight	Nonzero
ColorSpace	Unsigned integer	exif:ColorSpace	1..65535
ExposureTime / FNumber / FocalLength	Unsigned rational	Matching exif property	Nonzero numerator and denominator
IsoSensitivity	Unsigned integer	exif:ISO	Nonzero

Validation and threading

Text must be non-empty valid UTF-8 containing XML 1.0 character data. Hard limits are 1024 fields, 1 MiB of text per field, and 8 MiB of text per request. Request limits may lower but not raise those bounds. Date text is preserved but not parsed or normalized in this milestone.

The function uses no global state. Concurrent calls are safe when each call uses a distinct output store.

Python

import openmeta

K = openmeta.MetadataCreationFieldKind
document = openmeta.create_metadata([
    openmeta.metadata_creation_text(K.Title, "Evening frame"),
    openmeta.metadata_creation_text(K.Creator, "Alice"),
    openmeta.metadata_creation_u32(K.Orientation, 6),
    openmeta.metadata_creation_urational(K.ExposureTime, 1, 125),
])

The returned object is a normal Document. Invalid requests raise ValueError with the C++ status and rejected field index.

Use the matching transactional Editing API to modify these fields in an existing finalized store. See Metadata Editing.

Scope and safety

Creation emits canonical portable-XMP entries so existing sidecar and transfer writers can consume the result without original file-layout information. Direct EXIF/IPTC projection belongs to Translation.

Dimensions, orientation, and color space must describe destination pixels. They must not be copied from a differently sized, rotated, converted, or color-transformed source image. Custom properties, non-default languages, structured XMP, binary values, fresh ICC profiles, and direct EXIF/IPTC block construction remain outside this milestone.