Assets
Structured metadata
Last updated: Dec-11-2024
Overview
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.
Quick example
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:
\ or ", for example, \"text\" or ""text"".Metadata API methods
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.
| Method | Description |
|---|---|
GET/metadata_fields
|
Lists all metadata field definitions. |
GET/metadata_fields/:external_id
|
Returns a single metadata field definition by external ID. |
POST/metadata_fields
|
Creates a new metadata field definition. |
POST/metadata_fields/:external_id/datasource_restore
|
Restores entries in a metadata field datasource. |
POST/metadata_fields/:external_id/datasource/order
|
Order a metadata field datasource. |
PUT/metadata_fields/:external_id
|
Updates a metadata field definition by external ID. |
PUT/metadata_fields/:external_id/datasource
|
Updates a metadata field datasource by external ID. |
DELETE/metadata_fields/:external_id
|
Deletes a metadata field by external ID. |
DELETE/metadata_fields/:external_id/datasource
|
Deletes entries in a metadata field datasource for a specified metadata field definition. |
Metadata API field structure
Validating data
The 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.
For example:
Datasource values
The datasource parameter is relevant for fields where the selected values must come from a predefined list of values (enum or set type fields). The parameter contains the values property, which defines the values for the enum or set list. Up to 3000 values can be defined for a list.
For example:
Monitoring metadata changes using a notification URL
You can use Cloudinary notifications to 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.
To capture these changes, add a Notification URL triggered by the 'Resource metadata changed' Notification Type in the Webhook Notifications page of your Console Settings. The notification sent will specify resource_metadata_changed as the notification_type, and include 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:
for more information, see the documentation on Webhook Notifications.
Error
Rate this page:
