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 will:

• Improve your ability to manage your assets. Describing your assets in a meaningful way will increase asset searchability and discoverability.
• Open up a variety of options for programmatic operations. Storing descriptive information about your assets will enable developers to identify asset for different programmatic operations.
• Increase DAM navigability. Using structured metadata in a comprehensive way can replace the need for deep file structure as a method of classifying assets.

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 these fields are defined by a DAM administrator, all DAM 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 (string, number, date, list, etc), and other optional settings, such as range validation limits, whether the field is mandatory, a default value that will be automatically set for that field for new assets, and a custom ID value for developers to reference when managing metadata fields programmatically.

Defining how metadata is handled on upload

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

You can also determine how tags and contextual metadata 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. When this option is selected, existing tags and contextual metadata are kept when existing assets are overwritten. Otherwise, they are deleted.

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 for each field type, and set the list values for single and multiple-selection lists.

Additional options include:

For more detail on these options, see the Considerations section below.

To add a structured metadata field:

From the Product Navigation menu, 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.

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 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 string, number, and date fields, you can optionally set minimum and/or maximum values, a default value for new assets, and whether or not the field should be marked as mandatory, read-only, or hidden.
   • For single-selection or multiple-selection lists:
     1. Add the values you want to make available for your list.
        • Optionally select the Customize external ID checkbox to customize the list value's external ID value. The ID can include only alphanumeric, underscore, hyphen, and period characters. Once you click Set List Value to save the list value and its external ID, you won't be able to modify the list value's external ID.
        • Each new value is added to the end of the list, but you can drag it to the desired location (or use the Move to top/Move to bottom buttons). Up to 3000 values can be defined for a list.
     2. 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.

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 is subsequently uploaded to the Media Library. The field value will not 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.
• 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.
    • White spaces 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, you cannot 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.

• 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.
      Caution

      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. 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 configured that cause other fields to depend on it.

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 in the Admin API Reference and metadata 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 should not be available under certain conditions.

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'.
2. Selecting 'R&D' for the Team metadata field enables the Role metadata field with values such as 'QA', 'Devops' or 'Backend'.
3. 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 for more information.

1. From the Product Navigation menu, 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. 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:

   When	the field you select	Is empty or Is populated            OR	Includes or Equals a value you select...

5. Optionally, enter additional conditions 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 describes the actions you can set and gives a sample use case for each one.

Action summary table

Viewing and updating rules

To view and update rules:

1. From the Product Navigation menu, 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.

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