Last updated: Nov-08-2023
Cloudinary structured metadata allows you to define typed fields for media assets, populate them with values programmatically, via the Media Library and/or the Media Explorer, and perform searches on them. You can also add validation rules, set default values, and define fields as mandatory.
A metadata field is a custom, typed field (key) for storing user defined data (value) with a media asset.
This page explains the Metadata methods for creating and managing structured metadata fields, as well as the Metadata field structure and how to structure field validation and list (datasource) values.
Add a new mandatory metadata
set (multi-select) field with an external_id of 'color_id', labeled 'Colors', and with 4 available colors: red, green, blue and yellow, where red and green are the default values:
", for example,
The Metadata methods enable you to manage the metadata fields available for your product environment.
The table below provides a quick summary of the methods available for the Admin API
metadata_fields endpoint. See the Metadata reference documentation for more information on the following Metadata methods, as well as detailed information on the Metadata field structure, including how to work with field validation and list (datasource) values.
||Lists all metadata field definitions.|
||Returns a single metadata field definition by external ID.|
||Creates a new metadata field definition.|
||Restores entries in a metadata field datasource.|
||Updates a metadata field definition by external ID.|
||Updates a metadata field datasource by external ID.|
||Deletes a metadata field by external ID.|
||Deletes entries in a metadata field datasource for a specified metadata field definition.|
validation parameter defines a validation object with the logic to apply when a value is entered for the field, via the metadata, upload, explicit or update resource methods, or via the Media Library or the Media Explorer. The boolean validations also allow for combinations of more than one rule.
datasource parameter is relevant for fields where the selected values must come from a predefined list of values (
set type fields). The parameter contains the
values property, which defines the values for the
set list. Up to 3000 values can be defined for a list.
You can monitor for changes to the structured metadata on your media assets, including structured metadata that has been added or removed via API or the Cloudinary Console UI. These changes are sent as webhook notifications to the Notification URL specified in the Upload page of your Console Settings. To capture these changes, monitor for the response parameter:
resource_metadata_changed. Within it, you'll find information about which resource was changed, the source of the change (UI or API), and whether structured metadata was added, removed, or updated. For example:
See the documentation on Notifications for more information.