Metadata Mapping Reference

This reference document describes the mapping configuration used by all metadata import systems in Nomad Media, including:

• Sidecar metadata files
• EXIF metadata (images)
• ID3 tags (audio)
• Video metadata (MediaInfo)
• Document properties

Mapping Configuration Model

All metadata import configurations use the MetadataImportModel class to define how source metadata maps to asset attributes.

Mapping Properties

Example Mapping

{
  "sourceKey": "Keywords",
  "customMetadataProperty": "tags",
  "createNewContentRecord": true,
  "splitByDelimiter": ","
}

This mapping will:

1. Extract the Keywords field from the source metadata
2. Split the value by comma (e.g., "tag1, tag2, tag3" → ["tag1", "tag2", "tag3"])
3. For each value, find or create a tag (because createNewContentRecord is true)
4. Attach all tags to the asset

Special Target Properties

These target properties have special handling and are not stored in customProperties:

All other target properties are treated as custom attributes and must match a propertyName in the Asset Metadata definition.

Tag Auto-Creation

The createNewContentRecord flag controls tag creation behavior per mapping:

{
  "sourceKey": "Keywords",
  "customMetadataProperty": "tags",
  "createNewContentRecord": true
}

• true - Missing tags will be automatically created with the string value as the title
• false - Only existing tags will be matched; warnings logged for missing tags

This provides fine-grained control over which metadata sources can create new tags.

Value Splitting

The splitByDelimiter property allows splitting a single source value into multiple values:

{
  "sourceKey": "Keywords",
  "customMetadataProperty": "tags",
  "createNewContentRecord": true,
  "splitByDelimiter": ","
}

Common delimiters:

• "," - Comma (most common)
• ";" - Semicolon
• "|" - Pipe
• " " - Space

Example:

• Source value: "landscape, sunset, mountains"
• After splitting: ["landscape", "sunset", "mountains"]
• Each value is processed separately and attached to the asset

Notes:

• If splitByDelimiter is null or empty, the value is not split
• Whitespace is automatically trimmed from each split value
• Empty values after splitting are ignored

Type Validation and Conversion

The system automatically validates and converts metadata values to match the target field type:

Type Mismatch Handling:

• Type mismatches are logged as warnings
• The field is skipped (not imported)
• Processing continues with remaining fields

Lookup Resolution

For lookup and multiselect fields, the system supports two matching methods:

1. By GUID (Exact Match)

{
  "contentRating": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

2. By Title (String Match)

{
  "contentRating": "PG-13"
}

Matching Rules:

• Title matching is case-sensitive and must be exact
• If a GUID is provided, it must match an existing record ID
• If a title is provided, it's matched against the record's title field
• Invalid GUIDs or unmatched titles are logged as warnings and skipped

Error Handling

The system provides comprehensive error handling for all metadata processing:

All processing is logged with:

• Source metadata field and value
• Target property and type
• Validation results
• Conversion results
• Tag/collection creation results
• Any errors or warnings

Check CloudWatch logs for the asset processing Lambda functions to troubleshoot issues.