> ## Documentation Index
> Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom metadata


There are three types of metadata that can be stored with your assets: structured metadata, contextual metadata, and tags. These types of metadata are useful for [searching assets](dam_media_asset_search) based on a value or field value pair, or as a method of marking assets for a particular purpose in your end-user application. 

For example, your developer can set up a "Specials" page in your web store to display all assets where the structured metadata `sale` field is set to `campaign-A`. Or, all assets that show scarves can be auto-tagged with a value `scarf` to be displayed on your web store accordingly.

This enables Assets users from your creative, marketing, or sales teams to decide which assets get which field values or tags, while your developers take advantage of custom metadata API methods to implement the application side.

 

 Check out the Introduction to Cloudinary Assets pathway in the Cloudinary Academy for free self-paced courses on DAM topics.
 

## Custom metadata types

The following sections describe each of the three types custom metadata that can be stored within each asset in your product environment and explains the differences between them:

* **Tags**: individual text values that can be assigned to specific assets (up to 1000 tags allowed per asset).
* **Contextual metadata**: custom key-value pairs that you can assign to individual assets.
* **Structured metadata**: custom fields are defined, along with data types and validations, by a Assets administrator at a global level, and are added to all assets in the product environment. You assign their values per asset. 
  > **READING**:
>
> :no-title
>   On the **Assets Free** plan, you can have a limited number of structured metadata fields, and some related features are unavailable. The full feature is included in the Media Library for **Assets Enterprise** customers only. 

>    * To learn more about the features available in the **Assets Free** plan and how they can support development workflows, see [Media Library for Developers](media_library_for_developers). 

>    * For upgrade options or more information, [contact us](https://cloudinary.com/contact).

The following table compares the three types of metadata:

### Custom metadata comparison table 

{table:class=small-1stcol} | Tags | Contextual | Structured |
|---|---|---|---|
|**Scope** | Values are added individually to each asset, or to several assets in bulk, manually or through automatic tagging. | Fields and values are added individually to each asset. | Fields are defined for the entire product environment. The values are set individually for each asset. 
|**Created by**|Fields and values can be added by any user with write-level permissions for a particular asset. Your assets can also be automatically tagged using a Cloudinary [add-on](cloudinary_add_ons) during [upload](image_upload_api_reference#upload_method) or [update](admin_api#update_details_of_an_existing_resource) using AI image recognition and categorization capabilities.  | Fields and values can be added by any user with write-level permissions for a particular asset. | Fields are created and managed globally either by an Assets administrator in the [Manage Structured Metadata](dam_admin_structured_metadata#structured_metadata_management) page, accessible from the [Media Library Preferences](dam_admin_media_library_options#media_library_preferences) or by a developer via the [metadata API](structured_metadata). Any user with write-level permissions for a particular asset can add or edit the field values.	
|**Value types** | All values are unvalidated, free-text strings. | All fields are unvalidated, free-text strings. | Each metadata field is defined with a specific type (string, number, single or multi-select list, or date). The field can optionally be set with validation requirements (which can limit the values allowed in the field to, for example, a numeric range, number of characters, or regex pattern matching for strings). Fields may also have [conditional metadata](#conditional_metadata_bullet) rules applied that can change elements of their definition based on selections in other fields. (This feature is available only to **Assets Enterprise** customers, [by request](https://cloudinary.com/contact).)
|**Programmatic equivalent** | - Add, remove, and replace tags: [tags](image_upload_api_reference#tags_method) methods of the Upload API. - Add tags: [upload](image_upload_api_reference#upload_method) method of the Upload API.- View and add tags: [resource](admin_api#resource) methods of the Admin API.- Replace tags: [explicit](image_upload_api_reference#explicit_method) method of the Upload API.- View tags: [tags](admin_api#tags) method of the Admin API. | - Add fields and values: [context](image_upload_api_reference#context_method) method of the Upload API.- Add values: [upload](image_upload_api_reference#upload_method) and [explicit](image_upload_api_reference#explicit_method) methods of the Upload API.- View and add tags: [resource](admin_api#resource) method of the Admin API. | - Manage fields: [metadata_fields](structured_metadata#metadata_methods) method of the Admin API.- Set field values: [metadata](image_upload_api_reference#metadata_method), [upload](image_upload_api_reference#upload_method) and [explicit](image_upload_api_reference#explicit_method) methods of the Upload API.- View and set field values: [resource](admin_api#resources) methods of the Admin API.
|**Benefits** | This metadata type enables assets to be automatically classified and tagged, which is especially useful when managing assets in bulk. | This metadata type gives more control and flexibility to individual Assets users. | This metadata type enables more standardization across the organization. 

## Overview

You can set custom metadata values for an asset in the Media Library from the **Metadata** tab of the **Preview pane** and from the [Metadata tab](#setting_custom_metadata_values) of the [asset management drill-down](dam_manage_individual_assets#asset_management_drill_down) page. You can also set [structural metadata](#bulk_updating_structured_metadata), [tags and contextual metadata](#bulk_updating_tags_and_contextual_metadata) for multiple assets at once.

After you set metadata values for your assets, you can search for assets by those values adding them as **Custom filters** using the **Advanced Search**. For details, see [Search by metadata](dam_advanced_search#metadata).

The following sections cover some additional clarifications for setting [tags](#setting_tags), [contextual](#setting_contextual_metadata_values) metadata, [structured](#setting_structured_metadata_values) metadata, and bulk updating [structural metadata](#bulk_updating_structured_metadata), [tags and contextual metadata](#bulk_updating_tags_and_contextual_metadata) values.

 We invite you to try the free Help Users Find Files, Improve SEO and Support Accessibility with Metadata online workshop, where you can learn how to apply many forms of metadata to your assets to help improve management efficiency.

## Setting custom metadata values

You can set custom metadata for a single asset from the Metadata tab of the [asset management drill-down](dam_manage_individual_assets#asset_management_drill_down) page, including:

* Viewing or updating the asset's **custom metadata**, including tags, structured metadata, and contextual metadata.
* Viewing the asset's **embedded metadata** (such as the EXIF data stored with photos). 
  > **READING**:
>
> :no-title
>   This feature isn’t included in the Media Library available with the **Assets Free** plan, which offers basic management. It's part of the Media Library for **Assets Enterprise** plans.

>     * To learn more about the features available in the **Assets Free** plan and how they can support development workflows, see [Media Library for Developers](media_library_for_developers). 

>     * For upgrade options or more information, [contact us](https://cloudinary.com/contact).
  
To open the Metadata tab, either double-click the asset or select **Open** from the asset (3-dots) options menu, and select the Metadata tab.

![Asset Management Metadata tab](https://cloudinary-res.cloudinary.com/image/upload/bo_1px_solid_grey/f_auto/q_auto/v1710092923/manage_page_metadata_new.png "thumb: w_550,dpr_2, width:550, with_code:false, with_url:false, popup:true")

You can click **Discard Changes** to revert all your edits.

Make sure to **Save** your changes before leaving the page.

#### Metadata notes and tips

* Depending on the [Media Library preferences](dam_admin_media_library_options#media_library_preferences) set for your product environment, this tab may show both **structured and contextual metadata**, or it may only show one or the other of these.
* When you add, remove, or change the values in any editable section of the Metadata tab, the section is marked as **Editing...** and the **Save** button becomes enabled. When you're finished with changes to that section, you should save your changes. If you try to close the browser tab or navigate to another area of the Media Library or Console, you'll be prompted to save your changes. If you decide to close the tab or navigate away without saving, all changes to unsaved metadata sections will be reverted to their previous state. 
*  For assets with long lists of **embedded metadata**, you can use the **Filter data** box to find the type of embedded metadata you're looking for. Additionally, depending on the [Media Library preferences](dam_admin_media_library_options#media_library_preferences) set for your product environment, it's possible that only a select set of embedded metadata fields will be included in the list. (Embedded metadata fields are available in the Media Library to **Assets Enterprise** customers [by request](https://cloudinary.com/contact).)

### Setting tags

The **tags** shown in this tab include both tags that were added manually and any tags that were automatically generated by auto-tagging add-ons, either programmatically, during upload as defined by an [upload preset](upload_presets) or via the [Analysis tab](#analysis_tab) of the [asset management drill-down](dam_manage_individual_assets#asset_management_drill_down) page.

To manage tags more efficiently, you can copy all the **tags** from one asset and paste them in another.

### Setting contextual metadata values

> **NOTE**: This option may not be available if your Assets administrator has selected to hide it in the [Media Library preferences](dam_admin_media_library_options#media_library_preferences).

In each of the areas where you can edit contextual metadata, you will always see two suggested contextual metadata fields: `Title (caption)` and `Description (alt)`. If you add values for these, then those fields are added to the asset's custom metadata with the values you set. You can additionally or alternatively add any other field names and values in the **Custom metadata** section.  

![Sample contextual metadata in Asset Management page](https://cloudinary-res.cloudinary.com/image/upload/q_auto/f_auto/bo_1px_solid_grey/v1710093555/docs/DAM/context_metadata_tab.png "thumb: w_700,dpr_2, width:700, with_code:false, with_url:false, popup:true")

> **NOTE**: There is no technical difference between the suggested `Title (caption)` and `Description (alt)` fields and any other custom fields you add. If you don't need these two fields, you can leave them blank and add any other fields as needed. The suggested fields are just intended as a quick way for you to potentially add standard custom fields to your assets that your developers might use, for example, to display a title and description for the assets when they are displayed in your application.

### Setting structured metadata values

If your Assets administrator or a developer has defined structured metadata fields for your product environment, anyone with edit permissions for an asset can set the structured metadata field values in the **Metadata** tab of the **Preview pane** or from the **Metadata** tab of the [asset management drill-down](#asset_management_drill_down) page.

When working with structured metadata, the set of available fields is identical for all assets in your product environment. 

* **Field types**: Each field is predefined as one of the following types: free text field, multi-select list, single-selection list, number, or date. 
* **Validation rules**: Field values that can be manually entered, such as text, number, and date fields, may have been defined with validation rules, such as minimum or maximum values or regex pattern matching for text fields. If you enter a value that doesn't meet the validation rules, then when you click outside the field (which submits the value), an error message gives you information to help you correct the value.
* **Mandatory fields**: Some fields may be defined as mandatory. 
    * If an asset existed before your administrator defined the mandatory field, you are not immediately required to fill it in. However, if you click in a mandatory field and then click out of it (in essence submitting an empty value), you will receive a message that the value is mandatory. 
    * Similarly, if a mandatory field has a value, and you delete it, you will be required to enter a new value. Otherwise, when you change views, the field will revert to its previous value.

* **Conditional metadata**: (This feature is available only to **Assets Enterprise** customers, [by request](https://cloudinary.com/contact).) The behavior of some fields may depend on the values you enter in other fields. A field might appear, receive a default value, or display different choices in its list, depending on the values you enter in another field. For example, if you select **Employee** from the **Category** field, this might cause the **Department** field to appear, whereas if you select **Conference** from the **Category** field, the **Department** field isn't relevant and remains hidden. 
  > **NOTE**: If you change the value of a field that has dependencies, the values that you previously set in those dependent fields may be automatically deleted.

![Sample structured metadata in Asset Management page](https://cloudinary-res.cloudinary.com/image/upload/q_auto/f_auto/bo_1px_solid_grey/v1710094060/docs/DAM/structured_metadata_tab.png "thumb: w_750,dpr_2, with_code:false, with_url:false, width:750, popup:true")

### Dynamically adding list values to single and multiple-selection fields

If you have **Can edit** or **Can manage** permissions on an asset's containing folder, you can add list values to single or multiple-selection structured metadata fields permitted by your administrator. This provides flexibility to include list values that may not have been anticipated initially. 

Here's how you can dynamically add list values:

1. Navigate to the Structured Metadata section of the **Metadata** tab on the asset management drill-down page or Preview pane.
2. Click on the field you want to modify.
3. Enter the new list value and press `Enter` to save it to the field.
4. Remember, the new value won't be saved for the asset until you click the **Save** button to confirm the structured metadata modifications.

### AND vs OR metadata search conditions

* In general, when you perform an [advanced search](dam_advanced_search) in the Media Library, if you select multiple values for a specific search criteria, you will get results for assets that have ANY of those values, meaning these are treated as **OR** search conditions. For example, if you select 2 values from the **Tags** filter, you will get assets that have either of those tags. 
* Conversely, if you add more than one different search criteria, such as searching by both **Asset types** and **Formats**, your results will include only assets that match both of those criteria, meaning these are treated as **AND** search conditions. If you add structured metadata fields in your search filters, and if you add a free text search, they are all considered separate **AND** search conditions, as well. 
* When searching by [structured metadata fields](dam_advanced_search#custom_filters), if you enter more than one value WITHIN a multi-select field when searching, you can choose whether they are treated as **AND** conditions or as **OR** conditions. In the following example,  results would include only assets where **Categories** contains either `Shoes` OR `Gifts`, **Product ID** is less than `12345` AND **Publish Date** is before `Aug 1, 2019`.
  ![Search by structured metadata fields](https://cloudinary-res.cloudinary.com/image/upload/v1648992713/docs/DAM/structured_metadata_search.png "thumb: w_300,dpr_2, with_code:false, with_url:false, width:300, popup:true")
* Similarly, if you enter multiple [contextual metadata fields](dam_advanced_search#context_filter) in a search, you can choose whether the **AND** (assets returned have to match all fields) or the **OR** (assets returned have to match any of the fields) search condition is applied. In the following example, your search results would include any assets that have **campaign** = `ABC` OR **discount_code** = `blue` OR **aaa** = `aaa`.
  ![Search by contextual metadata fields](https://cloudinary-res.cloudinary.com/image/upload/v1648993829/docs/DAM/contextual_metadata_search.png "thumb: w_250,dpr_2, with_code:false, with_url:false, width:250, popup:true")

## Bulk updating structured metadata

* You can [edit structured metadata](#edit_structured_metadata) for multiple assets at a time by selecting assets from any view in the Media Library and then clicking the relevant option from the assets toolbar.

* In addition, administrators can update structured metadata in bulk by [importing a CSV file](#bulk_update_metadata_from_a_csv_file).
  > **READING**:
>
> :no-title
>   This feature isn’t included in the Media Library available with the **Assets Free** plan, which offers basic management. It's part of the Media Library for **Assets Enterprise** plans.

>     * To learn more about the features available in the **Assets Free** plan and how they can support development workflows, see [Media Library for Developers](media_library_for_developers). 

>     * For upgrade options or more information, [contact us](https://cloudinary.com/contact).

### Edit structured metadata

You can edit structured metadata for multiple assets at a time from directly within the Media Library. Select the assets you want to update and click the **Edit Structured Metadata** option from the assets toolbar to open the **Edit metadata** dialog box. In the **Assets Free** plan, this option is nested within the **Metadata** icon .

The placeholder for each field gives information about the previously existing metadata values stored in the selected assets, to help you verify the changes you're about to make: 

* If the field is empty, none of the selected assets have previously existing values in that field.
* If **Mixed values** is displayed, the selected assets have different previously existing values, or no value, in that field.
* If an actual value is displayed, that value exists in that field for all of the selected assets.

To update the values in a metadata field for all selected assets, select the field and then enter (or select) the corresponding values. 

When updating multi-selection type fields with **Mixed values**, you can choose to either **Override** previously selected options or **Append** new selections, leaving existing options unchanged. If the values in the multi-selection field are all the same (i.e., not **Mixed values**), you can add or delete selections. However, any changes to other field types will override previously existing values.

![Bulk edit structured metadata](https://res.cloudinary.com/release-notes/image/upload/q_auto/f_auto/bo_1px_solid_grey/v1731609024/bulk_update_structured_metadata.png "thumb:w_600,dpr_2, width:600, with_code:false, with_url:false, popup:true") 

#### Dependant fields

If your administrator has configured conditional metadata for your assets (available only to **Assets Enterprise** customers by request), additional fields may appear, disappear, or change depending on the values you enter. For example, selecting **Employee** from a **Category** field might display a **Department** field, because employees are associated with departments. By the same token, selecting **Conference** from the **Category** field might hide the **Department** field because it's no longer relevant, and in that case, any values previously selected for the **Department** field would be automatically deleted. 

When you update structured metadata in bulk, previously existing metadata values are not displayed. Also, only the highest-level fields appear initially, and any hidden fields are displayed only if the conditions that activate them are met. So, while you change values in higher-level fields, it's possible that this may automatically delete metadata in dependent, hidden fields. If at least one of the assets you are updating already contains a value in a hidden field, a message warns you that metadata in hidden fields may be deleted as you change values in fields they depend on. 

### Bulk update structured metadata from a CSV file

Administrators can update assets' structured metadata in bulk by importing a CSV file that contains all the assets and field value changes you want to make. For more information, see [Bulk update structured metadata from a CSV file](dam_admin_structured_metadata#bulk_update_structured_metadata_from_a_csv_file) in the Admin Guides.

## Bulk updating tags and contextual metadata

You can also set custom metadata values for multiple assets at once by selecting the assets from any view in the Media Library and then clicking the relevant option from the assets toolbar. 

### Tags

Click the **Tag** option from the assets toolbar to open the **Manage tags** dialog box, where you can add new tags and remove tags for the selected assets. The **Remove tags** option is included, but minimized, if at least one of the assets you selected has tags. In the **Assets Free** plan, the **Edit Tags** option is nested within the edit metadata icon  of the assets toolbar.

To remove tags from the selected assets, expand the **Remove tags** option and type or select the tag values you want to remove. The selection list shows tag values that exist for at least one of the currently selected assets. The values you include in the **Remove tags** field will be selectively removed from any assets that have them. If a selected asset does not have any of those tags, it is not affected by the **Remove** part of the operation. Tags you specify to add are added to all selected assets. 

### Contextual metadata

> **NOTE**: This option may not be available if your Assets administrator has selected to hide it in the [Media Library preferences](dam_admin_media_library_options#media_library_preferences).

Click the **More** option (...) from the assets toolbar and then click **Edit Contextual Metadata** in the drop-down menu to open the **Edit metadata** dialog box. Select an existing key and enter a matching value to add contextual metadata to your asset. You can also create a new key by entering a word in the **Key** textbox. 

In the **Assets Free** plan, the **Edit Contextual Metadata** option is nested within the edit metadata icon  in the assets toolbar.
{/reading}