> ## 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.

# Structured metadata


**Structured metadata fields** enable you to store descriptive information about your assets. 

When setting up your product environment, determine what information best serves your organization to classify and identify your assets, and create your structured metadata fields accordingly. 

A well planned structured metadata schema:

* **Improves your ability to manage your assets.** Describing your assets in a meaningful way increases asset searchability and discoverability.
* **Opens up a variety of options for programmatic operations.** Storing descriptive information about your assets  enables developers to identify asset for different programmatic operations.
* **Increases Media Library navigability.** Using structured metadata in a comprehensive way can replace the need for deep file structure as a method of classifying assets. 

> **READING**:
>
> :no-title
> On the **Assets Free** plan, you can use a limited number of structured metadata fields, and some related features are unavailable, as outlined on this page. 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).

## Overview

**Structured metadata fields** are a set of custom fields that you can define for each product environment. The defined fields are added to all assets in your Media Library. For example, you could create custom fields for **Product category**, **Status**, **Product ID**, **Rights expiration date** (for copyrighted materials), **Photographer**, etc. Each organization can decide on the fields that are most appropriate for its needs. 

Once an Assets administrator defines these fields, all Assets users (with relevant permissions) can then set values for these fields on individual assets. This enables better searchability of your assets as well as opening up a variety of options for programmatic operations that your developers can perform based on the metadata values. 

For each field you define, you can specify a field name, value type (text, number, date, list, etc), and other optional settings, such as [validation rules](#validations), whether the field is mandatory, a default value that's automatically set for that field for new assets, and a custom ID value for developers to reference when managing metadata fields programmatically.

![Structured metadata field creation](https://cloudinary-res.cloudinary.com/image/upload/bo_1px_solid_gray/f_auto/q_auto/v1703422509/docs/DAM/metadata_field_creation.png "thumb: w_750,dpr_2, width:750, with_code:false, with_url:false, popup:true") 

## Metadata and tags (video tutorial)

Watch this video tutorial to learn how to make your content searchable by adding metadata and tags.
> **NOTE**: If you're using the free plan, some of the functionality may differ from what's described in the video.

  This video is brought to you by Cloudinary's video player - embed your own!Use the controls to set the playback speed, navigate to chapters of interest and select subtitles in your preferred language.

### Tutorial contents This tutorial presents the following topics. Click a timestamp to jump to that part of the video.
### Asset structure overview
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=assetsOnboardingMetadataTags :min=0 :sec=00 :player=cld} | This is the first video in a two-part series that explores asset structure within the [Media Library](https://console.cloudinary.com/console/media_library) and how it can help you organize your Media Library content, making asset searches more efficient. This video focuses on metadata and tags. The [next video](assets_onboarding_folders_tutorial) covers folders.Asset Structure goes beyond the conventional notion of shared folders, drives, or desktops. With Assets (Digital Asset Management), you have the flexibility to create an organized structure using metadata and tags, as well. Together, these elements form the foundation for effective asset storage, search, and reuse, keeping all users up to date and assuring administrators that the right content is being delivered to employees. Additionally, Assets enables secure file sharing and seamless integration with a broader tech stack. |

### Metadata types
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=assetsOnboardingMetadataTags :min=1 :sec=43 :player=cld} | Metadata stores descriptive information about your asset, represented as fields and values. The three supported types of metadata are:  **Structured metadata**: primarily comprising labels and file names used for customized search purposes. **Contextual metadata**: offers a more detailed description, including titles and captions.  **Embedded metadata**: data integrated directly into the asset, such as EXIF information. Teams also have the option to add this metadata themselves if needed, such as when the asset has undergone editing using various applications. |

### Structured metadata
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=assetsOnboardingMetadataTags :min=2 :sec=34 :player=cld} | You can enhance the searchability of your content through the Media Library. (Developers can also achieve this via the [Metadata API](admin_api#metadata_fields).) Using the UI, you can navigate to [Structured Metadata](https://console.cloudinary.com/console/media_library/metadata_fields) in the Assets Product Navigation (accessible to administrators). Here, you'll discover a list of existing fields, each offering a unique way to search for assets based on their values.

### Structured metadata example
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=assetsOnboardingMetadataTags :min=3 :sec=36 :player=cld} | To illustrate, click  **Create a New Field** and establish a multiple-selection list called `Collections`, to categorize fashion brands according to their season. After creation, you can prioritize this field's position within the list. Add **List values** such as `SS22`, `SS23`, `AW22` and `AW23` in the right-hand panel to create new search options. 

### Set up and search by structured metadata 
{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=assetsOnboardingMetadataTags :min=4 :sec=35 :player=cld} | Back in the Media Library, select **Preferences** from the Assets Product Navigation, and in the **Advanced Search Filters** section, add the newly crafted `Collections` field. Upon returning to the Media Library and choosing the Assets view for filtering, you'll see your `Collections` field among the filters at the top. This provides a convenient way to filter assets based on their creation season, allowing you to efficiently assign and retrieve information for asset location. |

### View and edit metadata values in the asset management drill-down page

{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=assetsOnboardingMetadataTags :min=5 :sec=12 :player=cld} | To access and edit asset metadata, double click the asset to open the [asset management drill-down page](dam_manage_individual_assets), then select the **Metadata** tab. This tab allows you to view and modify your tags, structured metadata fields and contextual metadata fields by adding values as needed.  In the example shown, the tags were added automatically, structured metadata include `Gender`, `Asset Type`, `Link` to the asset, `Season`, `Approval Status`. This information is used to find and reuse assets stored within the platform.|

### Contextual and embedded metadata

{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=assetsOnboardingMetadataTags :min=6 :sec=18 :player=cld} | Contextual and embedded metadata play a significant role in asset management. Contextual metadata comprises titles and descriptions provided for assets, while embedded metadata includes data generated by creative agencies, third parties, or contained within the asset itself, such as EXIF data, resolution, camera information, and GPS location. All of these elements contribute to effective asset searching.

### Contextual and embedded metadata examples

{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=assetsOnboardingMetadataTags :min=6 :sec=57 :player=cld} | In the **Metadata** tab of the [asset management drill-down page](dam_manage_individual_assets), you'll find fields for **Title (caption)** and **Description (alt)** under **Contextual metadata**, as well as fields for **Embedded metadata**, including **DPI**. If you're in search of specific DPI values, you can easily locate them in a search. |

### Tags

{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=assetsOnboardingMetadataTags :min=7 :sec=37 :player=cld} | Tags provide a flexible, free text means of supplementing metadata, allowing you to attach information to assets. Tags can be applied manually or automatically using platform add-ons such as [Cloudinary AI Content Analysis](cloudinary_ai_content_analysis_addon), [Google Vision](google_auto_tagging_addon) and [Amazon Rekognition](aws_rekognition_auto_tagging_addon). 

### Adding tags manually

{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=assetsOnboardingMetadataTags :min=8 :sec=15 :player=cld} | For example, in the **Metadata** tab of the [asset management drill-down page](dam_manage_individual_assets) you can manually add a tag like `Stripes`, by typing it into the **Tags** textbox. 

### Auto-tagging

{table:class=tutorial-bullets}|  | 
| --- | --- |
|{videotime:id=assetsOnboardingMetadataTags :min=8 :sec=33 :player=cld} | You can also utilize auto-tags, setting a minimum confidence level. Tags that don't meet this minimum confidence threshold won't be suggested. You can then run the add-on and add selected suggested tags or add them all. These tagging options can also be enforced upon upload using an [upload preset](dam_admin_upload_presets), ensuring consistent tagging practices. For example, if you want to have auto-tagging applied to all uploads, you can configure an upload preset accordingly. |

## Defining how metadata is handled on upload
> **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).
You can control whether users are prompted to enter structured metadata values on every upload, or only when there are mandatory fields without default values, in the **Request structured metadata on upload** section of the [Media Library Preferences](dam_admin_media_library_options#media_library_preferences). When users are prompted to enter metadata while uploading, they can only continue once they've filled in valid values for all mandatory fields. For more details on structured metadata and uploading, see [Structured metadata on upload](dam_upload_store_assets#structured_metadata_on_upload).

You can also determine how [tags and contextual metadata](dam_manage_metadata#custom_metadata_comparison_table) are handled when existing assets are overwritten in the **Keep existing metadata when uploading newer versions of an asset** section of the [Media Library Preferences](dam_admin_media_library_options#media_library_preferences). When this option is selected, existing tags and contextual metadata are kept when existing assets are overwritten. Otherwise, they are deleted. 

> **INFO**:
>
> When uploading via the API, the **Keep existing metadata when uploading newer versions of an asset** determines the behavior of tags, contextual metadata, and structured metadata. Unless this option is selected, metadata of assets overwritten via the API is deleted. Coordinate with your development team when changing this setting.

## Adding structured metadata fields

You can create fields of several different types, including text, number, date, single-selection list, and multiple-selection list. You can assign the field a default value, set relevant [validations](#validations) for each field type, and set the list values for single and multiple-selection lists.

Additional options include:

|Option|Description|Field Types|Example Use Case
|---|---|---|---|
|[Customize external ID](#external_id) (field)| Allows you to customize the field's external ID, an identifier for programmatically referencing it. If left blank, an automatically generated value based on the field name will be assigned. | All | If programmers in your organization manage structured metadata fields, customizing the external ID makes their work more intuitive.For example, a programmer can set the **Now in stock** field to mandatory programmatically by accessing it via its customized external ID: `in_stock`.
|[Hide this field](#hidden)| Keeps the field hidden in the Media Library and disabled through the API until a matching [conditional rule](#managing_conditional_metadata_rules) activates it.If a field becomes **Hidden** in the Media Library via a matching conditional rule, it also becomes disabled through the API, and any previously entered values are cleared. | All | Initially hide and disable the **State** field, unless **USA** is selected as the value for the **Country** field. If a different selection is then made in the **Country** field, such as **Germany**, the **State** field becomes hidden in the Media Library, disabled in API, and all previous selections for **State** are cleared.
|[Read-only field](#read_only)| Prevents the field's values from being changed via the UI. Changes can only be made programmatically. | All | All metadata values are imported from a PIM, and the system needs to be protected from users accidentally changing values from the UI.
|[Default value](#default)| Sets a default value that automatically populates for new assets uploaded to the Media Library. | All | Set the **Status** field to default to `Draft` for all newly uploaded assets.
|[Mandatory field](#mandatory)| Ensures that a field is populated for all assets. | All | Users can't upload an asset while its **Product** field is left blank, and the value for the field can't be deleted.
|[Validations](#validations)| Enforces rules to ensure data quality and consistency.For **text** fields:**Min/max length**: Limit the number of characters**Regex pattern**: Validate specific formats (emails, UUIDs, SKU codes, URLs, etc.)For **number** fields:**Greater than/less than**: Set acceptable numeric rangesFor **date** fields:**Before/after**: Set acceptable date ranges | Text, number, date | Set a **Product Code** field to require exactly 8-12 charactersValidate that an **Email** field matches email format using regexEnsure a **Price** field is greater than 0 and less than 10000Restrict a **Launch Date** to be after 2020-01-01
| Allow users to add list values dynamically | Allows users with **Can edit** or **Can manage** permissions on an asset's containing folder to add list values to the structured metadata field. | Single and multiple-selection lists | While adding metadata to an asset, a user finds that the campaign the asset belongs to doesn't exist as a list value. So, the [user dynamically adds](dam_manage_metadata#dynamically_adding_list_values_to_single_and_multiple_selection_fields) the new campaign to the **Campaign** multi-selection field and saves the newly added list value in the asset's metadata.
|[Customize external ID](#external_id) (list value)| Allows you to customize a list value's external ID, an identifier for programmatically referencing it.If left blank, an automatically generated value based on the list value will be assigned. | Single and multiple-selection lists | If programmers in your organization manage structured metadata fields, customizing the external ID makes their work more intuitive.For example, if programmers decide to no longer support GIFs, they can easily reference the **GIF** list value via its customized external ID and delete it. |

For more detail on these options, see the [Considerations](#structured_metadata_field_considerations) section below.

**To add a structured metadata field:**

From the [Product Navigation menu](dam_digital_asset_management#assets_navigation_options), select **Structured Metadata** to open the Manage Structured Metadata page and then follow the steps shown in the animations below or follow the [written instructions](#read_about_how_to_create_fields).

#### Watch and learn: Create your first field (numeric)

#### Watch and learn: Create a multi-select field
   

#### Read about how to create fields:

These steps walk you through the process shown in the above animations, with some additional clarifications:

1. Click **Create a new field** and then define the field **Label** (display name) and **Field type**.  Optionally select the [Customize external ID](#external_id) checkbox to customize the field's external ID value. The ID can include only alphanumeric, underscore, hyphen, and period characters. 
2. Fill in the relevant options for the field type you chose:
    * For **text** fields, you can optionally set [min/max length or regex pattern validations](#validations), a [default value](#default) for new assets, and whether the field should be marked as [mandatory](#mandatory), [read-only](#read_only), or [hidden](#hidden).![Creating a text field with regex validation](https://cloudinary-res.cloudinary.com/image/upload/bo_1px_solid_grey/f_auto/q_auto/v1768480185/docs/DAM/text_smd_regex.png "thumb: w_350,dpr_2, width:350, with_code:false, with_url:false, popup:true")
    * For **number** fields, you can optionally set [greater than/less than validations](#validations), a [default value](#default) for new assets, and whether or not the field should be marked as [mandatory](#mandatory), [read-only](#read_only), or [hidden](#hidden).
    * For **date** fields, you can optionally set [before/after validations](#validations), a [default value](#default) for new assets, and whether or not the field should be marked as [mandatory](#mandatory), [read-only](#read_only), or [hidden](#hidden).
    * For **single-selection** or **multiple-selection** lists:
       1. Add the values you want to make available for your list:
          1. Click **Manage list values** to open the manage page.
          2. Optionally select the [Customize external ID](#external_id) checkbox to customize the list value's external ID value. The ID can include only alphanumeric, underscore, hyphen, and period characters.
          3. Enter a field **Label** and optionally an **External ID** and press 'Enter'. ![Single and multi-select structured metadata field manage page](https://res.cloudinary.com/release-notes/image/upload/f_auto/q_auto/bo_1px_solid_grey/v1731577965/single_multi_smd_manage_page.png "thumb:w_400,dpr_2, width:400, with_code:false, with_url:false, popup:true") 
            > **NOTES**:
>
> * Each new value is added to the end of the list, but you can drag it to the desired location (or use the **Move value to top of list**/**Move value to bottom of list** buttons). 

>                * Up to 3000 values can be defined for a list.

Optionally select one of the defined values as the default value, and whether or not the field should be marked as mandatory, read-only, or hidden. 
You can also:Edit the list value's name.Select **Block value for future use** from the (3-dots) option menu to hide the value. You can always make it visible again. Filter to find list values more easily.

#### Structured metadata field considerations

* When you create a new field, that field is immediately available from every asset in the Media Library.

* **Default value:** After you define a default value for a field, that value appears as the default value for any asset that's subsequently uploaded to the Media Library.  The field value won't be set retroactively for assets that were uploaded previously. 

* **List values:** You can block a list value from being selected by users. Blocking a list value doesn't delete the value from assets already using it, and you can unblock a list value anytime.

* **Validations:** You can set validation rules to ensure data quality and consistency:
    * **Text fields** can have:
        * **Minimum/maximum length**: Controls the number of characters allowed in the field
        * **Regular expression (regex) pattern**: Validates that values match a specific format (such as email addresses, UUIDs, SKU codes, URL slugs, etc.). When you define a regex pattern, users receive real-time validation feedback with helpful error messages as they type. 
        > **TIP**: For regex pattern examples and detailed API documentation, see [Validating data](admin_api#validating_data) in the Admin API reference.
    * **Number fields** can have:
        * **Greater than/less than**: Sets acceptable numeric ranges using greater than or less than comparisons (optionally with "equals")
    * **Date fields** can have:
        * **Before/after**: Sets acceptable date ranges using before or after comparisons (optionally with "equals")
    * Validation rules apply to new assets and any assets where the field is subsequently edited. Existing field values are not automatically validated or changed when you add or modify validation rules.

* **External ID:** The unique identifier for structured metadata fields and single and multiple-selection list values when programmatically handling structured metadata.You can customize this value. If you don't, the external ID will be assigned an automatically generated default value, based on the field name or the list value.
    * If you choose to customize external IDs, it's recommended to determine a standard naming convention for these together with the relevant developers.  
    * Automatically generated default values follow these guidelines:
        * If the field name or the list value has only alphanumeric characters, the external ID will be given the same value (capital letters changed to lowercase). Example: the list value is `Red`, so the external ID will be `red`.
        * Whitespaces or any of these characters ``-@#()+*.,:~[]{}<>/\=;`“?!_|`` included in the field name or list value are replaced with an underscore `_` in the external ID. Example: the field name is `Photographer Name`, so the external ID will be `photographer_name`.
        * If any non-alphanumeric character that is not listed above is included in the field or list value, the external ID is randomly generated. Example: the list value is `Black & white`, so the external ID will be `gxkeslnor1wj8hyux5cr`.
    * Once set, external IDs cannot be modified. 
    * External IDs (whether automatically generated or customized) can easily be copied and sent to developers as needed:
        * After a field has been created, the field's external ID is displayed in the field details pane.
        * After a list value has been created, the list value's external ID is displayed under the list value in the field details pane.  

* **Read-only field**: If a field is populated programmatically, you might want to set it as read-only to prevent unwanted changes to its values. 
    * A read-only field is viewable but not editable from the Media Library and can only be edited via the API. 
    * Assets can be searched from the Media Library by values in read-only fields. 
    * A field can be set to be either read-only or mandatory but not both.
    * A read-only field can have a default value.

* **Hidden field**: When you define a field as hidden, it's also disabled via the API. You can't initially assign it a default value, nor can you set it to mandatory. You can change the mandatory setting and assign a default value (as well as determining when it will be displayed) using [conditional metadata rules](#managing_conditional_metadata_rules). 
  > **INFO**:
>
> If a field becomes **Hidden** in the Media Library via a matching conditional rule, it also becomes disabled through the API, and any previously entered values are cleared.

* **Mandatory field**: 
    * You have a few ways to make sure that mandatory fields receive values:
        * Define fixed default values when defining the fields.
        * Create conditional metadata rules that assign them default values when they become visible.
        * Allow users to set the values when they are prompted during upload.
        
        Keep in mind that if you don't assign default values for mandatory fields, any developers in your organization must ensure that they pass field values for mandatory fields every time they upload an asset via the API. If they don't, their upload calls will fail.
        

    * Once a mandatory field has a value (either the default value or one that was set manually), users can modify the value, but they cannot remove the value and leave the field blank. For assets that existed in the Media Library before you set a field as mandatory, the field will initially remain untouched. However, if a user clicks in a mandatory field and then exits it without setting a value, they are notified that the field is mandatory.

## Managing existing structured metadata fields

After you create metadata fields, you can modify the field definitions, change the display order of fields or list values, block selected list values, or permanently remove a field. 

**Considerations:**

* Renaming a field takes effect immediately for all assets in the Media Library. You can also add additional values or modify value names for a single or multiple selection list, and these changes will take place immediately for all assets. 
* If you modify the value name (display text) of an existing list value, this change will also impact assets where the previous name was selected. Thus you should change existing list values only to fix spelling or make the value more clear for users, but you should not change the significance of the value once it's in use. If you want to make a completely different option available, add it as a new value.
* If you no longer want a value to be available for selection, you can **block** the value. This removes the value from the selection options in the list for all assets, but does not delete or modify the value for any assets where that value is currently selected.
* Even after a list item is blocked, you can still search for assets with that value in the [Advanced Search](dam_advanced_search). This can be useful to find all assets that used a value you've blocked to change them to other values.
* Other changes to the definition of a field, such as adding, removing, or modifying default values, changing validation rules, changing the mandatory setting, etc., impact new assets added to the Media Library after the change. Existing assets are affected by these changes only if a user chooses to edit that field.
* You can also permanently delete an entire field. When you delete a field, the values that were set for that field in existing assets are also permanently removed. You can't delete a field if there are [metadata rules](#managing_conditional_metadata_rules) configured that cause other fields to depend on it.

## Setting a primary attribute
> **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 set a primary attribute, select **Use as primary attribute** from the field's (3-dots) option menu in the Manage Structured Metadata page.
You can select a single-select structured metadata field or a built-in asset attribute (such as access control) as the **primary attribute** to ensure its constant visibility to users. This displays the attribute's value: 

* Overlaid on asset previews on homepage search results.
* Overlaid on asset previews in Card and Mosaic views and as the first column in List view within Assets, Folders, Collections, and Moderation.
* On the [asset management drill-down page](dam_manage_individual_assets#asset_management_drill_down). 

Furthermore, you can color-code the attribute's possible values (list values) to make it easier to identify specific states.

For example, if there's a structured metadata field or a built-in asset attribute like access control with crucial status that needs to be readily visible in the Media Library, you can designate it as the **Primary attribute**. 

![Primary attribute](https://cloudinary-res.cloudinary.com/image/upload/f_auto/q_auto/bo_1px_solid_grey/v1707823915/docs/DAM/primary_attribute.png "thumb:w_700,dpr_2, with_code:false, with_url:false, width:700, popup:true")

> **TIP**: You can also set a primary attribute from the [Display](dam_admin_media_library_options#display) tab of the Preferences page.

## Modifying field definitions and values programmatically 

In addition to creating, updating, or deleting fields, or setting field values in the Console, structured metadata fields and values can also be created, updated, or removed programmatically by developers in your organization using Admin and Upload API methods.

**For example:**

* Add a very long list of possible values to a field, where the values are pulled from external data, such as a list of cities or countries, a set of product codes, a list of suppliers, etc. It may be easier for a developer to create a script to automatically capture and add all the values than for you to add them manually.

* Update field values for thousands of assets at once. A developer could use the Search API to find all assets that fit certain criteria and then set the metadata fields for all returned assets to the appropriate values.

* Capture data from other parts of your application and use that data to assign metadata values to assets that your end-users upload. For example, a programmer could set metadata field values to a customer username, options the customer selected in your application and more, and store that data with the assets they upload, so that this data can then be used for other application features. For example, you could then allow your end users to search for all photos they uploaded or display a page with all photos that customers marked as belonging to a selected category. 

* Your developer could create a small application to monitor changes in an external system, such as a PIM, or status management system, and then those changes could trigger programmatic changes to asset metadata values or the possible values of a metadata field.

For details, see [metadata_fields](admin_api#metadata_fields) in the Admin API Reference and [metadata](image_upload_api_reference#metadata_method) in the Upload API Reference.

## Managing conditional metadata rules

When setting up structured metadata fields, you may want to design it so that some fields depend on the values entered in others, meaning that some fields or field values only become relevant if certain selections are made or conversely some fields or values shouldn't be available under certain conditions. 

> **READING**:
>
> :no-title
> **Assets Enterprise plans**:

> * The **conditional metadata rules** feature is a premium offering for **Assets Enterprise** plans, and its availability depends on your account setup. If **conditional metadata rules** isn't yet enabled for your account and you'd like to activate it, please contact your Customer Success Manager. 
> **Assets Free plans**:

> * 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).
**Conditional metadata rules** allow you to set up dependencies and hierarchical relationships between structured metadata fields and field options. This allows you to:

* Enable/disable (show/hide) another metadata field based on the value selected for a metadata field.
* Activate options displayed for a particular metadata field based on the value specified in another field.
* Set the default metadata value in a particular field based on the value specified in another field.

Some popular use cases for conditional metadata include:

* High-level file type selection, for example: setting metadata fields on different types of content such as image, video and document.
* Support segmenting into categories, for example: product imagery vs lifestyle photography.
* Document asset usage rights, for example: stock imagery.
* Support large organizations with multiple metadata schemas.

For example, one of the metadata fields can include various category values for photos on a company intranet site, such as 'Employee', 'Conference', and 'Culture'. You could set up rules based on these values as follows:

1. Selecting 'Employee' in the **Category** metadata field enables (displays) the **Team** metadata field with values such as 'R&D', 'Product' or 'HR'. 
1. Selecting 'R&D' for the **Team** metadata field enables the **Role** metadata field with values such as 'QA', 'Devops' or 'Backend'.
1. Selecting 'QA' for the **Role** metadata field enables the **Name** metadata field with the members of the QA team: 'John Smith' or 'Jane Kelly'. If Devops had been selected for the **Role** metadata field, then the **Name** field would be enabled with members of the Devops team: 'Paul Green' or 'Mary Rose'.

### Adding rules

You can add one or more rules to a field, and each rule can have one or more [conditions and actions](#conditional_metadata_rule_considerations) for more information. 

> **NOTE**: When you configure several rules on a single field, it's important to consider their order carefully because each subsequent rule can overwrite the actions of the rules before it. For example, one rule can add options to the field's multiple-selection list and another can remove or change them; one can show the field and another can hide it; one can add a default value and another can change it.

1. From the [Product Navigation menu](dam_digital_asset_management#assets_navigation_options), select **Structured Metadata** to open the Manage Structured Metadata page. 
   
2. Select the field whose behavior you want to set as a _result_ of the condition you are adding. For example, if selecting the value **Red** from the **Color** field (condition) causes **Pink** and **Maroon** to be displayed in the **Color shade** field (result), then you should create the rule on the **Color shade** field.

    > **NOTE**: If you want this field to remain hidden unless a certain condition is met, enable **Hide this field**. If the field is hidden, it cannot initially be a mandatory field, and it cannot contain a default value. In addition, it's disabled through the API. However, you can add a rule whose action displays the field, assigns it a default value, and / or makes it mandatory.

3. In the right-hand panel, click **Manage rules**, then click **Create a rule** to open the **Create Rule** screen and enter a descriptive **Rule name**.
4. Click **Add condition** and select the field and condition options that express your case.  
   
    The condition is presented as a natural English sentence with the following structure: 

    {table:class=no-borders no-headings}  |   | | | 
    ---|---|---|---|
    **When** | _the field you select_  |  ***Is empty*** or ***Is populated*** &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;OR |***Includes*** or ***Equals***  _a value you select_... 

5.  Optionally, enter [additional conditions](#conditional_metadata_rule_considerations) and select **Match one (OR)** or **Match all (AND)**.
6.  Click **Add action** to determine what happens to your selected field when the condition you set is met. The [Action summary table](#action_summary_table) describes the actions you can set and gives a sample use case for each one. 

![Structured metadata rule creation](https://cloudinary-res.cloudinary.com/image/upload/bo_1px_solid_gray/f_auto/q_auto/v1636553298/docs/DAM/metadata_rule_creation.png "thumb: w_550,dpr_2, width:550, with_code:false, with_url:false, popup:true") 

#### Action summary table
{table:class=small-1stcol} Action | Description | Use-case example | 
|---|---|---|---|
|**Show field** | The dependent field is hidden by default and displayed if the condition is met. | If the value of the **Category** field is **Employee**, the **Department** field is displayed. 
|**Hide field**| The dependent field is displayed by default and is hidden if the condition is met. | The default value for the **Country** field is **USA**, and the **State** field appears. If the value of for the **Country** field is changed to **England**, the **State** field becomes hidden. 	
|**Set field as mandatory** | The dependent field becomes mandatory. | All assets can optionally receive an **Expiration date**, but If the asset's **Copyright** field is set to **Yes**, then the **Expiration date** field becomes mandatory. 
|**Set field as optional** | The dependent field becomes optional. | **Color** is crucial to track for most assets and is therefore set to mandatory by default, unless the asset's **Category** is **Oldies**, in which case **Color** is not always a factor, so the Color field can be set to optional. 
|**Set default value(s)** | A default value is set for the dependent field. | This condition can be used with the **Show field** action. For example, the value **Employee** is chosen from the field **Category**, causing the **Department** field to be displayed. When the field is displayed, it's assigned a default value, **R&D**.
|**Append values** | Automatically sets one or more values to the dependent field and displays them as selected (only if the user hasn't made a selection manually). | If the value **Snow** is selected for the **Category** field, the option **Winter campaign** is appended to the **Campaign** field, and is displayed as a selected value in that field.
|**Show all options** | All available options of a single or multiple-selection list in the dependent field are displayed, when some of the options configured for the list may have previously been hidden. | When **Usage Rights** is set to **Public**, the asset can be displayed in all possible **Venues**, as opposed to when **Usage Rights** is set to **Internal** and a limited number of **Venues** are available.
|**Show no options** | Clears all available options in a single or multiple-selection list in the dependent field. This is useful when you want to start with an empty list and add displayed values as conditions are met. | The **Color Shades** field is initially cleared using the **Show no options** action. When the color **Blue** is selected from the **Color** field, the **Color Shades**: **Light Blue** and **Navy** options are displayed using the **Show the following additional options...** action. When the color **Red** is added, red **Color Shades** options are additionally displayed.
|**Show only the following options...** | Defines the available options in the single or multiple-selection list in the dependent field. | The **Roles** field displays different options based on the **Department** chosen.
|**Show the following additional options...** | Additional options (that may have been hidden) are added to the single or multiple-selection list in the dependent field. | Certain core **Categories** of images are used all year round, but in **Summer** the category **Swimwear** is added.

### Viewing and updating rules

**To view and update rules:**

1. From the [Product Navigation menu](dam_digital_asset_management#assets_navigation_options), select **Structured Metadata** to open the Manage Structured Metadata page.
2. If a field has a rule already configured, **Has rules** appears in the field description. Select the field whose rules you want to view or update and click **Manage rules**. A summary of the configured rules for that field appears.
3. Click **Edit** and make changes to a rule. Drag and drop the rule to its desired position.

![Structured metadata rule summary](https://cloudinary-res.cloudinary.com/image/upload/bo_1px_solid_gray/f_auto/q_auto/v1630569819/docs/DAM/metadata_rule_summary.png "thumb: w_550,dpr_2, width:550, with_code:false, with_url:false, popup:true") 

### Conditional metadata rule considerations

* You can add multiple conditions to determine a specific action. For example, you may want a specific list of **Videographers** to appear only if the value for the **File type** field is **Video** _and_ the value for the **Category** field is **Nature**. 
    
    If your action depends on multiple conditions, you can select **Match one (OR)** to apply the action when ANY one of the conditions are met, or **Match all (AND)** to apply the action only when ALL of the conditions are met.

* Actions are grouped according to their similar functions. (**Show field** is grouped with **Hide field**, **Set field as mandatory** is grouped with **Set field as optional**, etc.) You can only add one action from the same group in a single rule. For example, if you've already added **Show only the following options...**, you won't be able to also add **Show the following additional options...**. However, you can add a new rule to the field to set the desired action.

* From the [Manage Structured Metadata](#structured_metadata_creation_screencap) page, order your fields hierarchically so that when dependent fields appear, they are displayed directly below the fields they depend on.

* When [users update metadata in bulk](dam_manage_individual_assets#bulk_updating_metadata_values), values in dependent fields may be automatically deleted if values of fields that they depend on are changed.

* A field that has dependencies can't be deleted.

> **NOTE**: Structured metadata is always available to the user for viewing and setting. However, you can hide contextual metadata from the user's view in the [Media Library Preferences](dam_admin_media_library_options#media_library_preferences).

## View and add metadata values

You can view and add metadata values via the Metadata tab of the asset Manage page. In particular:

* View or update the asset's **custom metadata**, including tags, structured metadata, and contextual metadata.
* View 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 Asset Management 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_650,dpr_2, width:650, with_code:false, with_url:false, popup:true")

#### Metadata notes and tips

* 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](dam_analysis_insights#analyze_assets).
* You can copy all the **tags** from one asset and paste them in another.
* 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.
  * **Structured metadata** fields are defined globally for the product environment. Users with edit permissions for the asset can update the values in this tab.  
  * **Contextual metadata** fields are defined individually for each asset. Users with edit permissions for the asset can add or remove fields and values.    

    For more details, see [Custom metadata](dam_manage_metadata).
* 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. 
* You can [bulk update structured metadata](dam_manage_metadata#bulk_updating_structured_metadata), either directly from the Media Library or by importing a CSV file. You can also [bulk update tags and contextual metadata](dam_manage_metadata#bulk_updating_tags_and_contextual_metadata) from the Media Library.
* 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.

## Bulk update structured 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).
{/reading}
You can update your assets' structured metadata in bulk by importing a CSV file that contains all the assets and field value changes you want to make. You can update up to 10,000 assets in a single import. 

To bulk update structured metadata, follow these steps:

1. [Prepare your CSV file](#prepare_your_csv_file)
2. [Import your CSV file and update](#import_your_csv_file_and_update_your_asset_metadata).

#### Step 1 - Prepare your CSV file

To prepare your own CSV file, first download the CSV file containing your current metadata using the **Export Metadata** [DAM app](dam_admin_media_library_options#dam_apps), then change any of the values you want to update in the file:

1. Select the assets you want to update, then select **Export Metadata** from the assets toolbar. 
  ![Export Asset Metadata DAM app](https://cloudinary-res.cloudinary.com/image/upload/f_auto/q_auto/v1675292505/docs/DAM/export_metadata_menu.png "thumb: w_500,dpr_2, with_code:false, with_url:false, width:500, popup:true")
  > **NOTE**:
>
> If the **Export Asset Metadata** DAM app isn't accessible in the assets toolbar, an administrator can enable it from the [App Marketplace](https://console.cloudinary.com/console/media_library/apps) page of the Console. For more information, see [Dam Apps](dam_admin_media_library_options#dam_apps).
1. From the **Export Asset Metadata** dialog box, select the required identifier fields: 
   * If you want to use the asset's public ID as the identifier, you must select all three fields, `Public ID`, `Asset Type`, and `Delivery Type`, but NOT the `Asset ID` field.
   * If you want to use asset ID as the identifier, you must select the `Asset ID` field but NOT the `Public ID`, `Asset Type`, and `Delivery Type` fields.
2. Select any structured metadata fields you want to update.
3. Export your CSV file.
4. Edit the field values in the CSV file that you want to update. Fields that are left blank won't be updated. 

Alternatively, prepare a CSV file on your own: 

1. Click the (3-dots) options menu at the top right of the Media Library and select **Bulk Update Metadata**.
   ![Media Library (3-dots) options menu](https://cloudinary-res.cloudinary.com/image/upload/v1677063288/docs/DAM/bulk_update_metadata_csv "thumb: w_300,dpr_2, with_code:false, with_url:false, width:300, popup:true")
2. Download the sample file containing the required unique asset identifier column(s) that you want to use, either `publicId` or `assetId`.
3. Edit the CSV file:
   * Add columns that map to the structured metadata fields you want to update.
   * Fill in the CSV file with the relevant asset details. Fields that are left blank won't be updated. 

**CSV file requirements:**

In order for the import and update to succeed, the CSV file must contain:

  * Columns that map to and have the same name as the asset's unique identifier. Include only **one** of the following sets of columns in your CSV file, either: 
    * `assetId`
      OR
    * `publicId` together with `assetType` and `deliveryType`
  * Additional columns that map to existing structured metadata fields.
    > **NOTE**: Make sure your CSV file contains only columns that correspond to one of the asset identifier sets, i.e., either `assetId` OR `publicId`, `assetType` and `deliveryType`, and structured metadata fields. Any extra columns, or duplicated columns, will cause the import to fail. 
  * Rows that represent up to 10,000 assets, without duplicates.
  
For the asset to update successfully, its row must contain:

  * A valid value in the column(s) that map to the asset's unique identifier. 
  * A unique identifier that matches an existing asset.
  * A valid value for each structured metadata field column, e.g., a column that maps to a structured metadata field of type `date` must contain a date in the required format (YYYY-MM-DD).

When metadata rules are applied to your schema: 

* Verify that your CSV file includes necessary parent columns according to the conditional rules. For any particular row, populate these parent columns with values that satisfy the condition in the specified conditional rule. This step is necessary to enable adding values in the dependent fields. For instance, if a metadata rule allows entry of states only when the United States is chosen, in your CSV file, you can input `CA` and `PA` into the `State` column for a specific row only if the `Country` column for that row exists and contains `USA`. For more information, see [Managing conditional metadata rules](dam_admin_structured_metadata#managing_conditional_metadata_rules).

#### Step 2: Import your CSV file and update your asset metadata

If you haven't yet opened the bulk update, click the (3-dots) options menu at the top right of the Media Library and select **Bulk Update Metadata**.

![Media Library (3-dots) options menu](https://cloudinary-res.cloudinary.com/image/upload/v1677063288/docs/DAM/bulk_update_metadata_csv "thumb: w_300,dpr_2, with_code:false, with_url:false, width:300, popup:true")

Import your CSV file and run the update. 
  
An email will be sent to you when the update is complete, containing a full report of the asset metadata. This report will show values for all the assets and metadata fields that had been listed in the CSV file, including values that were and weren't updated, and any errors that may have occurred.