Metadata Importing

Nomad Media supports multiple methods for importing metadata into assets:

1. Sidecar Metadata Files - JSON files placed alongside media assets
2. EXIF Metadata - Embedded metadata from image files (JPEG, TIFF, etc.)
3. ID3 Tags - Embedded metadata from audio files (MP3, M4A, etc.)
4. Video Metadata - Embedded metadata from video files via MediaInfo
5. Document Properties - Embedded metadata from document files (PDF, Office docs, etc.)

All metadata import methods share a unified processing system that supports:

• Mapping source metadata keys to custom attributes
• Mapping to special fields (tags, collections, language, dates)
• Type validation and automatic conversion
• Lookup value resolution (by ID or title)
• Configurable tag auto-creation per mapping
• Value splitting with delimiters
• Consistent error handling and logging

📘

Mapping Configuration Reference

All metadata import methods use the same mapping configuration model. See the Metadata Mapping Reference for detailed information about:

• Mapping properties (sourceKey, customMetadataProperty, createNewContentRecord, splitByDelimiter)
• Special target properties (tags, collections, language, dates)
• Tag auto-creation behavior
• Value splitting with delimiters
• Type validation and conversion
• Lookup resolution
• Error handling

Sidecar Metadata Files

Sidecar files with metadata properties can be imported automatically. This is most often used when external metadata exists for the media but is not contained within the media file itself — for example, dates, locations, tags, or other metadata that is commonly added to media in this fashion.

Rules

The following rules must be followed:

1. The metadata file must exist in the same folder as the associated asset.
2. For file assets, the metadata file must be named with the same name as the asset file, with .metadata appended to the end. For example:
   • image.jpg → image.jpg.metadata
   • cool-contents.json → cool-contents.json.metadata
3. Folder assets are also supported. For a folder asset, place the metadata file inside the folder and name it after the folder, with .metadata appended. For example:
   • content/videos/videos.metadata → content/videos/
   • 2024/january/january.metadata → 2024/january/
   • a/b/c/c.metadata → a/b/c/
4. The contents of the metadata file are in JSON format as a single dictionary (see File Format below).

Additionally:

1. A job runs every 5 minutes to scan for metadata files.
2. When a metadata file is found, the system looks for the associated asset by removing .metadata from the filename and searching the same folder. This supports both standard file assets and folder assets whose metadata file matches the containing folder name. If no matching asset is found, the metadata file is ignored.
3. When the file matches, the system opens and parses the metadata file contents.
4. After the metadata is successfully attached to the asset, the metadata file is moved to the metadata-archive bucket and associated as a related asset of the original file.
5. Metadata is stored in the internal customProperties attribute of the file manifest, except for the specific fields noted in the table below. All custom key values are merged into the search record for the asset.
6. The metadata file is then removed from the folder and will no longer appear in the UI. It remains accessible as a related asset of the original file for historical purposes.

Configuration

To enable automatic sidecar metadata file processing, set processMergeMetadataAssets to true in the nomadApplication section of the system configuration:

"application/nomadSettings": {
  "processMergeMetadataAssets": true,
  "mergeMissingMetadataFields": false
}

Configuration Options:

• processMergeMetadataAssets - Enable/disable sidecar metadata file processing
• mergeMissingMetadataFields - If true, ignores fields that don't exist in custom attributes; if false, returns an error for unknown fields

File Format

The metadata file is a JSON file with the .metadata extension, containing a single dictionary:

{
  "key1": "key1-value",
  "key2": "key2-value"
}

Notes about entries:

1. Each key is compared against the propertyName field in the Asset Metadata definition — the property name must exist or an error will be returned (unless mergeMissingMetadataFields is true).
2. The value's data type (boolean, date, guid, string, number) must match the field type or an error will be returned. For example, boolean values must be true or false; date values should use standard JSON format like "2025-10-06T14:00:00Z".
3. Dropdown choices (single and multi-select) accept either the record ID or the title string. Using the record ID guarantees an exact match. Titles are matched exactly against the content definition's record list — if the title is not found, an error is returned.

Special Fields

The following keys are handled differently and are not stored in customProperties:

EXIF Metadata Import

EXIF (Exchangeable Image File Format) metadata is automatically extracted from image files during asset processing. You can configure which EXIF fields map to custom attributes or special fields.

Configuration

Add EXIF import mappings to your system configuration:

"application/exifMetadataImportSettings": {
  "importMappings": [
    {
      "sourceKey": "Make",
      "targetProperty": "cameraMake",
      "createNewContentRecord": false
    },
    {
      "sourceKey": "Model",
      "targetProperty": "cameraModel",
      "createNewContentRecord": false
    },
    {
      "sourceKey": "Keywords",
      "targetProperty": "tags",
      "createNewContentRecord": true,
      "splitByDelimiter": ","
    },
    {
      "sourceKey": "DateTimeOriginal",
      "targetProperty": "createdDate",
      "createNewContentRecord": false
    }
  ]
}

Mapping Configuration

See the Metadata Mapping Reference for complete details on mapping properties including splitByDelimiter for handling multi-value fields.

Common EXIF Fields

Special Field Mapping Example

EXIF metadata can map to special fields like tags:

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

This mapping will:

1. Extract the Keywords EXIF field
2. Split the value by comma if it's a string (e.g., "landscape, sunset, mountains")
3. For each keyword, find or create a tag (because createNewContentRecord is true)
4. Attach all tags to the asset

ID3 Metadata Import (Audio)

ID3 tags are automatically extracted from audio files (MP3, M4A, etc.) during asset processing. Configure which ID3 fields map to custom attributes or special fields.

Configuration

Add ID3 import mappings to your system configuration:

"application/id3MetadataImportSettings": {
  "importMappings": [
    {
      "sourceKey": "TIT2",
      "targetProperty": "songTitle",
      "createNewContentRecord": false
    },
    {
      "sourceKey": "TPE1",
      "targetProperty": "artist",
      "createNewContentRecord": false
    },
    {
      "sourceKey": "TALB",
      "targetProperty": "album",
      "createNewContentRecord": false
    },
    {
      "sourceKey": "TCON",
      "targetProperty": "tags",
      "createNewContentRecord": true
    }
  ]
}

Common ID3 Frame IDs

Video Metadata Import

Video metadata is extracted from video files using MediaInfo during asset processing. This includes technical metadata from General, Video, and Audio tracks.

Configuration

Add video metadata import mappings to your system configuration:

"application/videoMetadataImportSettings": {
  "importMappings": [
    {
      "sourceKey": "General - Title",
      "targetProperty": "videoTitle",
      "createNewContentRecord": false
    },
    {
      "sourceKey": "General - Performer",
      "targetProperty": "performer",
      "createNewContentRecord": false
    },
    {
      "sourceKey": "General - Genre",
      "targetProperty": "tags",
      "createNewContentRecord": true
    },
    {
      "sourceKey": "Video - Format",
      "targetProperty": "videoCodec",
      "createNewContentRecord": false
    }
  ]
}

Common Video Metadata Fields

Video metadata fields are prefixed with the track type:

Document Metadata Import

Document properties are extracted from document files (PDF, Office documents, etc.) during asset processing.

Configuration

Add document metadata import mappings to your system configuration:

"application/documentMetadataImportSettings": {
  "importMappings": [
    {
      "sourceKey": "Title",
      "targetProperty": "documentTitle",
      "createNewContentRecord": false
    },
    {
      "sourceKey": "Author",
      "targetProperty": "author",
      "createNewContentRecord": false
    },
    {
      "sourceKey": "Subject",
      "targetProperty": "subject",
      "createNewContentRecord": false
    },
    {
      "sourceKey": "Keywords",
      "targetProperty": "tags",
      "createNewContentRecord": true,
      "splitByDelimiter": ","
    }
  ]
}

Common Document Properties

See Also

• Metadata Mapping Reference - Complete reference for mapping configuration, type validation, lookup resolution, and error handling
• Metadata Import Configuration - Configuration guide for EXIF, ID3, video, and document metadata import