Metadata API reference
Cloudinary structured metadata allows you to define typed fields for media assets, populate them with values programmatically or via the Media Library, 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 overall structure of a metadata field and how to structure field validation and list (datasource) values. You'll need to use these elements to create and manage structured metadata fields via the Admin API metadata
method.
For details on the available metadata
method options, see the metadata method in the Admin API Reference.
Generic structure of a metadata field
{ "external_id": <string>, "type": <field_type_enum>, "label": <string>, "mandatory": <boolean>, "default_value": <field_type_value>, "validation": <validation_object>, "datasource": <datasource_object> //enum and set types }
Parameter | Required | Description |
---|---|---|
external_id |
No | A unique immutable identification string for the metadata field. Default: auto-generated by Cloudinary (although it's recommended to specify a descriptive name). Max character length: 255. |
type |
Yes | The type of value that can be assigned to the metadata field, possible types are limited to: * string - a single string value* integer - a single integer value* date - a custom date in the following format: {yyyy-mm-dd}* enum - a single value referenced by an external_id from a given list, predefined with the datasource parameter* set - multiple values referenced by external_id s from a given list, predefined with the datasource parameter |
label |
Yes | The label of the metadata field for display purposes. |
mandatory |
No | Whether a value must be given for this field, either when an asset is first uploaded, or when it is updated. Default: false |
default_value |
Yes (if mandatory is true) |
The default value for the field (a set can have multiple default values defined by an array). Default: null |
validation |
No | Any validation rules to apply when values are entered (or updated) for this field. See Validating data for more details. Default: null |
datasource |
Yes (for the enum and set type ) |
The predefined list of values, referenced by external_id s, available for this field. See Datasource values for more details. |
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. The boolean validations also allow for combinations of more than one rule. The following validations are supported:
greater_than validation
Relevant for integer
and date
types:
Property | Type | Description |
---|---|---|
value |
String | The value for validation. |
equals |
Boolean | Whether to check if greater than or equals. Default: false |
For example:
less_than validation
Relevant for integer
and date
types:
Property | Type | Description |
---|---|---|
value |
String | The value for validation. |
equals |
Boolean | Whether to check if less than or equals. Default: false |
For example:
strlen validation
Relevant only for string
types:
Property | Type | Description |
---|---|---|
min |
Integer | The minimum string length. Default: 0 |
max |
Integer | The maximum string length. Default: 1024 |
For example:
and validation
Relevant for all field types. Allows you to include more than one validation rule to be evaluated:
Property | Type | Description |
---|---|---|
validation_object |
Object | One of the other validations above: greater_than , less_than or strlen |
For example:
"validation":{ "type": "and" "rules": [{ "type": "greater_than", "value": 10, "equals": true }, { "type": "less_than", "value": 50, "equals": true }] }
Datasource values
The datasource
parameter is only relevant for fields where the selected values must come from a predefined list of values (enum
or set
type fields). The parameter contains only the values property, in order to be future compatible with different kinds of datasource types.
Each datasource_entry
defines a single possible value for the field:
Property | Type | Description |
---|---|---|
external_id |
String | (optional) A unique immutable identification string for the datasource entry, (required if the value is referenced by the default_value field). Default: auto-generated by Cloudinary |
value |
String | (mandatory) The value for this datasource. |
state |
String | (read only) Only given as part of a response - ignored on requests. It is immutable unless changed via DELETE of a datasource entry. |
For example: