Cloudinary Logo Docs Documentation
  • Get Started
    • Programmable Media
      • Developer get started guide
      • Service overview
      • Try it! Explorers and demos
      • Using Cloudinary Postman collections
      • How are transformations counted?
      • Glossary
      • Release notes
    • Digital Asset Management
      • DAM get started guide
      • Release notes
    • Video tutorial library
      • Programmatic asset management
      • Transformations and optimizations
      • Digital Asset Management (DAM)
      • Administration
      • Platform integrations
  • Guides
    • Media upload
      • Overview
      • Uploading assets
      • Transformations on upload
      • Analysis on upload
      • Upload presets
      • Upload API reference
    • Image transformations
      • Image transformations overview
      • Resizing and cropping
      • Placing layers on images
      • Effects and enhancements
      • Face-detection based transformations
      • Animated images
      • Transformations on 3D models
      • Conditional transformations
      • User-defined variables and arithmetic transformations
      • Custom functions
      • Image collage generation
    • Video transformations
      • Video transformations overview
      • Resizing and cropping
      • Trimming and concatenating
      • Placing layers on videos
      • Effects and enhancements
      • Adaptive bitrate streaming
      • Converting videos to animated images
      • Audio transformations
      • Conditional transformations
      • User-defined variables and arithmetic transformations
      • Live streaming
      • Video slideshow generation
      • Video generation
    • Media delivery
      • Media optimization
      • Responsive images
      • Deliver remote media files
      • Social media profile pictures
      • Paged and layered media
      • Media access methods
      • Sprite generation
      • Advanced URL delivery options
    • Asset administration
      • Overview
      • Managing assets
      • Backups and version management
      • Account usage data
      • Webhook notifications
      • Signatures
    • Widgets and players
      • Upload Widget
      • Media Library Widget
      • Media Editor
      • Product Gallery
      • Video Player
    • Add-ons
      • Advanced Facial Attributes Detection
      • Amazon Rekognition AI Moderation
      • Amazon Rekognition Video Moderation
      • Amazon Rekognition Auto Tagging
      • Amazon Rekognition Celebrity Detection
      • Aspose Document Conversion
      • Cloudinary AI Background Removal
      • Cloudinary AI Content Analysis
      • Cloudinary Duplicate Image Detection
      • Google AI Video Moderation
      • Google AI Video Transcription
      • Google Auto Tagging
      • Google Automatic Video Tagging
      • Google Translation
      • Imagga Auto Tagging
      • Imagga Crop and Scale
      • JPEGmini Image Optimization
      • Perception Point Malware Detection
      • Microsoft Azure Video Indexer
      • Neural Artwork Style Transfer
      • OCR Text Detection and Extraction
      • Pixelz - Remove the Background
      • URL2PNG Website Screenshots
      • VIESUS™ Automatic Image Enhancement
      • WebPurify Image Moderation
    • Digital Asset Management
      • DAM overview
      • DAM user guide
      • DAM administrator guide
    • Media Optimizer
      • Overview
      • Quick starts
      • Configuration
      • Dashboard
      • Reports
      • Transformations
    • Platform integrations
      • Adobe Creative Cloud Connector
      • Akeneo PIM Integration
      • Chrome Media Library Extension
      • Magento Extension
      • Salesforce Commerce Cloud Cartridges
      • Salesforce Marketing Cloud App
      • SAP Commerce Extension
      • Shopify App
      • WordPress Plugin
      • Zapier Integration
      • Partner-built integrations
      • How to build your own integration
    • Pre-releases and labs
      • MediaFlows (Private Beta)
      • AR/3D Viewer and 3D Model Configurator
      • Media Inspector browser extension
  • References
    • Transformation URL API
    • Upload API
    • Admin API
    • Search API
    • Structured metadata
      • Metadata API
      • Conditional metadata rules API
    • Provisioning API
    • Cloudinary CLI
    • Postman collections
    • Upload Widget API
    • Video Player API
    • Product Gallery API
    • Media Editor API
    • Media Optimizer
      • Media Optimizer API
      • Transformation reference
  • SDKs
    • Backend SDKs
      • Ruby/Rails SDK
      • PHP SDK
      • Python SDK
      • Node.js SDK
      • Java SDK
      • .NET SDK
      • Go SDK
      • Dart SDK
      • PHP SDK (Legacy)
    • Frontend SDKs
      • JavaScript SDK
      • Angular SDK
      • React SDK
      • Vue.js SDK
      • jQuery SDK
      • JavaScript SDK (Legacy)
      • Angular SDK (Legacy)
      • React SDK (Legacy)
      • Vue.js SDK (Legacy)
    • Mobile SDKs
      • iOS SDK
      • Android SDK
      • Flutter SDK
      • Kotlin SDK
    • Community-developed libraries
      • Gatsby
      • Gridsome
      • Laravel
      • Netlify
      • Next.js
      • NuxtJS
      • Storefront UI
BlogTrainingSupportPricingCommunityMediaJamsPodcastsDemosRoadmapCookbookAdditional Resources
  • Blog
  • Training
  • Support
  • Pricing
  • Community
  • MediaJams
  • Podcasts
  • Demos
  • Roadmap
  • Cookbook
  • Additional Resources
Login
sign up for free
  • Get Started
    • Programmable Media
      • Developer get started guide
      • Service overview
      • Try it! Explorers and demos
      • Using Cloudinary Postman collections
      • How are transformations counted?
      • Glossary
      • Release notes
    • Digital Asset Management
      • DAM get started guide
      • Release notes
    • Video tutorial library
      • Programmatic asset management
        • Upload programmatically
        • Create upload presets
        • Auto-tag assets
        • Diagnosing error codes
        • Upload assets in a React app
        • Deliver images with the Next.js Image component
        • Generate upload signature
        • Postman collections introduction
        • Find your credentials
        • Configure the Node.js SDK
        • Get started with the CLI
        • Scripting with the CLI
        • Get creative with the CLI
        • Upload with the CLI
        • Upload Widget
        • Product Gallery
        • Product Gallery accessibility
      • Transformations and optimizations
        • Transformation basics
        • Optimization tips
        • Gravity-based crops for images
        • Text overlay transformations
        • Complex transformations
        • Named transformations
        • Advanced image components
        • Zoompan effect
        • Social media image cards in Next.js
      • Digital Asset Management (DAM)
        • Folder sharing
        • Collection management
        • Collection sharing
        • Transformation presets
        • Media Library upload
        • Video management intro
        • Advanced Search
      • Administration
        • Enable automatic backups
        • Restore asset versions
        • Restore deleted assets
      • Platform integrations
        • Adobe CC Connector overview
        • SAP Commerce Extension overview
        • SFCC site cartridge intro
        • SFCC site cartridge installation
        • SFCC site cartridge modes
        • SFCC site cartridge videos
        • SFCC Page Designer cartridge
        • SFMC app - image block
        • SFMC app - video to GIF block
        • Shopify app
  • Guides
    • Media upload
      • Overview
      • Uploading assets
      • Transformations on upload
      • Analysis on upload
      • Upload presets
      • Upload API reference
    • Image transformations
      • Image transformations overview
      • Resizing and cropping
      • Placing layers on images
      • Effects and enhancements
      • Face-detection based transformations
      • Animated images
      • Transformations on 3D models
      • Conditional transformations
      • User-defined variables and arithmetic transformations
      • Custom functions
      • Image collage generation
    • Video transformations
      • Video transformations overview
      • Resizing and cropping
      • Trimming and concatenating
      • Placing layers on videos
      • Effects and enhancements
      • Adaptive bitrate streaming
      • Converting videos to animated images
      • Audio transformations
      • Conditional transformations
      • User-defined variables and arithmetic transformations
      • Live streaming
        • Live streaming WebRTC (Beta)
        • Live streaming RTMP
        • Simulated live streaming
      • Video slideshow generation
      • Video generation
    • Media delivery
      • Media optimization
        • Optimize images
        • Optimize videos
        • Optimize audio files
      • Responsive images
        • Using HTML and dynamic image transformations
        • Using JavaScript frontend frameworks
        • Using the cloudinary-core JS library
        • Using client hints
      • Deliver remote media files
      • Social media profile pictures
      • Paged and layered media
      • Media access methods
      • Sprite generation
      • Advanced URL delivery options
    • Asset administration
      • Overview
      • Managing assets
      • Backups and version management
      • Account usage data
      • Webhook notifications
      • Signatures
    • Widgets and players
      • Upload Widget
      • Media Library Widget
      • Media Editor
      • Product Gallery
      • Video Player
        • Video Player features
        • Installation and setup
        • How to embed the Video Player
        • Video Player customization
        • Playlists and recommendations
        • HLS and MPEG-DASH
        • Events and analytics
        • Video ads and monetization
        • Shoppable Video
        • Interactive Video (Beta)
        • Video Player API reference
    • Add-ons
      • Advanced Facial Attributes Detection
      • Amazon Rekognition AI Moderation
      • Amazon Rekognition Video Moderation
      • Amazon Rekognition Auto Tagging
      • Amazon Rekognition Celebrity Detection
      • Aspose Document Conversion
      • Cloudinary AI Background Removal
      • Cloudinary AI Content Analysis
      • Cloudinary Duplicate Image Detection
      • Google AI Video Moderation
      • Google AI Video Transcription
      • Google Auto Tagging
      • Google Automatic Video Tagging
      • Google Translation
      • Imagga Auto Tagging
      • Imagga Crop and Scale
      • JPEGmini Image Optimization
      • Perception Point Malware Detection
      • Microsoft Azure Video Indexer
      • Neural Artwork Style Transfer
      • OCR Text Detection and Extraction
      • Pixelz - Remove the Background
      • URL2PNG Website Screenshots
      • VIESUS™ Automatic Image Enhancement
      • WebPurify Image Moderation
    • Digital Asset Management
      • DAM overview
      • DAM user guide
        • Uploading and storing assets
        • Folders and collections
        • Media asset search
          • Global Search
          • Advanced Search
          • Query Builder
          • Visual Search (Beta)
        • Managing individual media assets
      • DAM administrator guide
        • User and group management
          • SAML provisioning
        • Settings and preferences
          • Dynamic folders
        • Upload presets
        • Structured metadata
        • Asset management
        • Usage data
        • Dynamic templating
    • Media Optimizer
      • Overview
      • Quick starts
        • Walkthrough
        • Deliver from a web address
        • Deliver from an AWS S3 bucket
        • Deliver from a Google Storage bucket
        • Deliver using an HTTP proxy
      • Configuration
      • Dashboard
      • Reports
      • Transformations
    • Platform integrations
      • Adobe Creative Cloud Connector
      • Akeneo PIM Integration
      • Chrome Media Library Extension
      • Magento Extension
        • Magento product catalog API
      • Salesforce Commerce Cloud Cartridges
        • Page Designer Cartridge
          • Custom integration
        • Site Cartridge
          • Operational overview
          • Site Cartridge for SiteGenesis
          • Site Cartridge for SFRA
          • Site Cartridge FAQ
      • Salesforce Marketing Cloud App
      • SAP Commerce Extension
      • Shopify App
        • User guide
      • WordPress Plugin
        • Developer guide
      • Zapier Integration
      • Partner-built integrations
        • Agility Custom Field
        • Actindo Connection
        • Builder.io App Extension
        • Chioro Operation
        • Comestri Channel
        • Conscia Connector
        • Contentful App
        • Contentstack Custom Field Extension
        • Creative Force Asset Delivery
        • GraphCMS UI Extension
        • Kontent.ai Custom Element
        • Magnolia DAM Connector
        • Movidmo Upload Connector
        • OpenText TeamSite Connector
        • Sanity Plugin
        • Sitefinity DAM System Integration
        • Smint.io Data Source Connector
        • Stackbit Integration
        • Storyblok App Integration
        • Syndigo Advanced DAM App
        • Uniform Integration
        • Vue Storefront Component
      • How to build your own integration
    • Pre-releases and labs
      • MediaFlows (Private Beta)
        • Oveview
        • Getting started
        • Build your first flow
        • Block reference
      • AR/3D Viewer and 3D Model Configurator
        • Oveview
        • Customizations
        • 3D Model Configurator
      • Media Inspector browser extension
  • References
    • Transformation URL API
    • Upload API
    • Admin API
    • Search API
    • Structured metadata
      • Metadata API
      • Conditional metadata rules API
    • Provisioning API
    • Cloudinary CLI
    • Postman collections
    • Upload Widget API
    • Video Player API
    • Product Gallery API
    • Media Editor API
    • Media Optimizer
      • Media Optimizer API
      • Transformation reference
  • SDKs
    • Backend SDKs
      • Ruby/Rails SDK
        • Ruby/Rails introduction
        • Ruby/Rails quick start
        • Ruby/Rails image and video upload
        • Ruby/Rails image transformations
        • Ruby/Rails video transformations
        • Ruby/Rails asset administration
        • CarrierWave integration
        • Attachinary integration
        • Active Storage integration
      • PHP SDK
        • PHP introduction
        • PHP quick start
        • PHP image and video upload
        • PHP image transformations
        • PHP video transformations
        • PHP asset administration
        • PHP SDK reference
      • Python SDK
        • Python introduction
        • Python quick start
        • Python image and video upload
        • Python image transformations
        • Python video transformations
        • Python asset administration
      • Node.js SDK
        • Node.js introduction
        • Node.js quick start
        • Node.js image and video upload
        • Node.js image transformations
        • Node.js video transformations
        • Node.js asset administration
      • Java SDK
        • Java introduction
        • Java quick start
        • Java image and video upload
        • Java image transformations
        • Java video transformations
        • Java asset administration
      • .NET SDK
        • .NET introduction
        • .NET quick start
        • .NET image and video upload
        • .NET image transformations
        • .NET video transformations
        • .NET asset administration
      • Go SDK
        • Go introduction
        • Go quick start
        • Go image and video upload
        • Go media transformations
        • Go asset administration
        • Go SDK Reference
      • Dart SDK
        • Dart introduction
        • Dart media transformations
      • PHP SDK (Legacy)
        • PHP introduction
        • PHP image and video upload
        • PHP image transformations
        • PHP video transformations
        • PHP asset administration
        • PHP migration guide
    • Frontend SDKs
      • JavaScript SDK
        • JavaScript introduction
        • JavaScript quick start
        • JavaScript image and video upload
        • JavaScript image transformations
        • JavaScript video transformations
        • JavaScript SDK reference
        • Transformation Builder reference
      • Angular SDK
        • Angular introduction
        • Angular quick start
        • Angular image and video upload
        • Angular image transformations
        • Angular video transformations
        • Angular SDK reference
        • Transformation Builder reference
      • React SDK
        • React introduction
        • React quick start
        • React image and video upload
        • React image transformations
        • React video transformations
        • React SDK reference
        • Transformation Builder reference
      • Vue.js SDK
        • Vue.js introduction
        • Vue.js quick start
        • Vue.js image and video upload
        • Vue.js image transformations
        • Vue.js video transformations
        • Transformation Builder reference
      • jQuery SDK
        • jQuery introduction
        • jQuery image and video upload
        • jQuery image transformations
        • jQuery video transformations
      • JavaScript SDK (Legacy)
        • JavaScript introduction
        • JavaScript image and video upload
        • JavaScript image transformations
        • JavaScript video transformations
        • JavaScript migration guide
      • Angular SDK (Legacy)
        • Angular introduction
        • Angular image and video upload
        • Angular image transformations
        • Angular video transformations
        • Angular migration guide
      • React SDK (Legacy)
        • React introduction
        • React image and video upload
        • React image transformations
        • React video transformations
        • React migration guide
      • Vue.js SDK (Legacy)
        • Vue.js introduction
        • Vue.js image and video upload
        • Vue.js image transformations
        • Vue.js video transformations
        • Vue.js migration guide
    • Mobile SDKs
      • iOS SDK
        • iOS introduction
        • iOS image and video upload
        • iOS image transformations
        • iOS video transformations
      • Android SDK
        • Android introduction
        • Android image and video upload
        • Android image transformations
        • Android video transformations
      • Flutter SDK
        • Flutter introduction
        • Flutter media transformations
      • Kotlin SDK
        • Kotlin media transformations
    • Community-developed libraries
      • Gatsby
      • Gridsome
      • Laravel
      • Netlify
      • Next.js
      • NuxtJS
      • Storefront UI
Login
sign up for free
  • Guides
  • Digital Asset Management
  • DAM administrator guide
  • Structured metadata

Structured metadata

Last updated: Jan-16-2023

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.

Structured metadata field creation

On this page:

  • Overview
  • Defining how metadata is handled on upload
  • Adding structured metadata fields
  • Managing existing structured metadata fields
  • Modifying field definitions and values programmatically
  • Managing conditional metadata rules

Defining how metadata is handled on upload

Note
This feature is available by default to DAM customers on all plans. If you are eligible and this feature is not yet activated on your account or product environment, contact support.

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.

Important
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 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 (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 Hides the field unless a conditional rule is met. All Initially hide the State field, unless USA is selected as the value for the Country field.
Mandatory field 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.
Read-only field 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.
Customize 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 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.

Note
This feature is available only to Cloudinary customers on an Enterprise plan.

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.

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

Structured metadata rule creation

Action summary table

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

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.

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.

✔️ Feedback sent!

✖️  
How helpful was this doc page?

Thanks for submitting your rating. We got it!
We'd love to hear more. Tell us what you liked and how we can make this page even better:

*


Cloudinary is committed to protecting your information security. For details, see our privacy policy.

For additional assistance, open a support request.

Error

Unfortunately there's been an error sending your feedback.

Rate this page:

  • Managing upload presets in the DAM
  • Asset management
Cloudinary Logo - White
Products
  • Programmable Media
  • DAM
  • Demos
  • Pricing
  • Roadmap
  • FAQ
Solutions
    • Why Cloudinary
    • Video API
    • E-commerce
    • Retail
    • Media & Entertainment
    • Travel & Hospitality
    • Non-Profits
    • Our Customers
    • Resource Library
    Developers
    • Getting Started
    • Documentation
    • SDKs
    • Add-ons
    • Podcasts
    • Cookbook
    Company
    • About Us
    • Customers
    • Partners
    • Events
    • Careers
    • Newsroom
    • Blog
    • Brand Assets
    • Trust
    Contact Us
    • Technical Support
    • Contact Sales
    • Education & Training
    • Institute of Quality & Control
    • GDPR
    • SOC
    • Forbes Best Startup Employers 2020
    • MarTech Breakthrough Awards
    • Best Places to Work SVBJ 2018
    • 2020 The World's Best Cloud Companies
    • Terms of Use
    • Privacy Policy
    • DMCA Notice

    © 2023 Cloudinary. All rights reserved.