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
}

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
• less_than
• strlen
• and

greater_than validation

Relevant for integer and date types:

{
    "type": "greater_than",
    "value": <value_by_type>,
    "equals": <boolean>
}

For example:

"validation":{ 
    "type": "greater_than",
    "value": "2018-10-15",
    "equals": true
}

less_than validation

Relevant for integer and date types:

{
    "type": "less_than",
    "value": <value_by_type>,
    "equals": <boolean>
}

For example:

"validation":{ 
    "type": "less_than",
    "value": 50,
    "equals": true
}

strlen validation

Relevant only for string types:

{
    "type": "strlen",
    "min": <positive integer>,
    "max": <positive integer>
}

For example:

"validation":{ 
    "type": "strlen",
    "min": 5,
    "max": 20
}

and validation

Relevant for all field types. Allows you to include more than one validation rule to be evaluated:

{
    "type": "and",
    "rules": [ <validation_object>, <validation_object>, … ]
}

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.

{
    "values": [ <datasource_entry>, <datasource_entry>, … ]
}

Each datasource_entry defines a single possible value for the field:

{
    "external_id": <string>,
    "value": <string>,
    "state": "active" | "inactive"
}

For example:

"datasource": {
    "values": [{
        "external_id": "color1", 
        "value": "red"
    },
    {   
        "external_id": "color2", 
        "value": "green"
    },
    {
        "external_id": "color3", 
        "value": "blue"
    },
    {
        "external_id": "color4", 
        "value": "yellow"
    }]
}