Cloudinary Logo Docs Documentation
  • Get Started
    • Developer solution
      • How to integrate Cloudinary
      • Service overview
    • DAM solution
    • Video tutorial library
      • Digital Asset Management (DAM)
      • Programmatic asset management
      • Transformations and optimizations
      • Administration
      • Platform integrations
  • Guides
    • Media upload
      • Overview
      • Uploading assets
      • Transformations on upload
      • Analysis on upload
      • Upload presets
      • Upload API reference
    • Image transformations
      • Common image transformations
      • Face-detection based transformations
      • Chained and named transformations
      • Conditional transformations
      • User-defined variables and arithmetic transformations
      • Animated images
      • Transformations on 3D models
      • Custom functions
    • Video transformations
      • Common video transformations
      • Conditional transformations
      • User-defined variables and arithmetic transformations
      • Converting videos to animated images
      • Audio transformations
      • Live streaming (Beta)
      • Video slideshow generation (Beta)
    • Media delivery
      • Media optimization
      • Responsive images
      • Deliver remote media files
      • Social media profile pictures
      • Paged and layered media
      • Media access control
      • Sprite generation
      • Advanced URL delivery options
    • Asset administration
      • Overview
      • Managing assets
      • Backups and version management
      • Notifications
      • Signatures
    • Widgets and players
      • Upload Widget
      • Media Library Widget
      • Media Editor (ALPHA)
      • Product Gallery
      • Video Player
    • Digital Asset Management
      • Overview
      • Uploading and storing assets
      • Folders and Collections
      • Advanced search
      • Managing individual media assets
      • Media Library administration
  • References
    • Transformation URL API
    • Upload API
    • Admin API
    • Search API
    • Metadata API
    • Provisioning API
    • Cloudinary CLI
    • Upload Widget API
    • Video Player API
    • Product Gallery API
  • Integrations
    • SDKs
      • Ruby On Rails SDK
      • PHP SDK v2 (Beta)
      • PHP SDK
      • Django SDK
      • Node.js SDK
      • Java SDK
      • .NET SDK
      • JavaScript SDK
      • jQuery SDK
      • Angular SDK
      • React SDK
      • Vue.js SDK
      • iOS SDK
      • Android SDK
      • Kotlin SDK (Beta)
      • Community-developed libraries
    • Add-ons
      • Adobe Photoshop Lightroom
      • 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 Object-Aware Cropping
      • 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
      • MetaDefender Anti-Malware Protection
      • 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
    • Platforms
      • Adobe Creative Cloud Connector
      • Magento Extension
      • Salesforce Commerce Cloud Cartridges
      • WordPress Plugin
      • Zapier Integration
      • Third-party-developed integrations
TrainingBlogDemosSupportRoadmapCookbookWebinarsFacebook CommunityThe Visual Web
  • Training
  • Blog
  • Demos
  • Support
  • Roadmap
  • Cookbook
  • Webinars
  • Facebook Community
  • The Visual Web
Login
sign up for free
  • Get Started
    • Developer solution
      • How to integrate Cloudinary
      • Service overview
    • DAM solution
    • Video tutorial library
      • Digital Asset Management (DAM)
        • Dashboard intro
        • Sharing folders
        • Media Library intro
        • Media Library upload
        • Video management intro
        • Advanced search
      • Programmatic asset management
        • Upload programmatically
        • Generate upload signature
        • Get started with the CLI
        • Scripting with the CLI
        • Get creative with the CLI
        • Upload with the CLI
        • Product Gallery
      • Transformations and optimizations
        • Transformation basics
        • Optimization tips
        • Complex transformations
        • Named transformations
        • Lightroom edits
        • Advanced image components
      • Administration
        • Enable automatic backups
        • Restore asset versions
        • Restore deleted assets
        • Create an upload preset
      • Platform integrations
        • SFCC site cartridge intro
        • SFCC site cartridge installation
        • SFCC site cartridge modes
        • SFCC site cartridge videos
        • SFCC Page Designer cartridge
        • Cloudinary-Shopify Zap
  • Guides
    • Media upload
      • Overview
      • Uploading assets
      • Transformations on upload
      • Analysis on upload
      • Upload presets
      • Upload API reference
    • Image transformations
      • Common image transformations
      • Face-detection based transformations
      • Chained and named transformations
      • Conditional transformations
      • User-defined variables and arithmetic transformations
      • Animated images
      • Transformations on 3D models
      • Custom functions
    • Video transformations
      • Common video transformations
      • Conditional transformations
      • User-defined variables and arithmetic transformations
      • Converting videos to animated images
      • Audio transformations
      • Live streaming (Beta)
        • Live streaming WebRTC (Beta)
        • Live streaming RTMP (Beta)
      • Video slideshow generation (Beta)
    • Media delivery
      • Media optimization
        • Image optimization
        • Video optimization
      • Responsive images
      • Deliver remote media files
      • Social media profile pictures
      • Paged and layered media
      • Media access control
      • Sprite generation
      • Advanced URL delivery options
    • Asset administration
      • Overview
      • Managing assets
      • Backups and version management
      • Notifications
      • Signatures
    • Widgets and players
      • Upload Widget
      • Media Library Widget
      • Media Editor (ALPHA)
      • 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 (Alpha)
        • Video Player API reference
    • Digital Asset Management
      • Overview
      • Uploading and storing assets
      • Folders and Collections
      • Advanced search
      • Managing individual media assets
      • Media Library administration
        • SAML provisioning
  • References
    • Transformation URL API
    • Upload API
    • Admin API
    • Search API
    • Metadata API
    • Provisioning API
    • Cloudinary CLI
    • Upload Widget API
    • Video Player API
    • Product Gallery API
  • Integrations
    • SDKs
      • Ruby On Rails SDK
        • Rails integration overview
        • Rails image and video upload
        • Rails image transformations
        • Rails video transformations
        • Rails asset administration
        • CarrierWave integration
        • Attachinary integration
        • Active Storage integration
      • PHP SDK v2 (Beta)
        • PHP v2 integration overview
        • PHP v2 image and video upload
        • PHP v2 image transformations
        • PHP v2 video transformations
        • PHP v2 asset administration
        • PHP v2 migration guide
        • PHP SDK reference
      • PHP SDK
        • PHP integration overview
        • PHP image and video upload
        • PHP image transformations
        • PHP video transformations
        • PHP asset administration
      • Django SDK
        • Django integration overview
        • Django image and video upload
        • Django image transformations
        • Django video transformations
        • Django asset administration
      • Node.js SDK
        • Node.js integration overview
        • Node.js image and video upload
        • Node.js image transformations
        • Node.js video transformations
        • Node.js asset administration
      • Java SDK
        • Java integration overview
        • Java image and video upload
        • Java image transformations
        • Java video transformations
        • Java asset administration
      • .NET SDK
        • .NET integration overview
        • .NET image and video upload
        • .NET Image Transformations
        • .NET video transformations
        • .NET asset administration
      • JavaScript SDK
        • JavaScript integration overview
        • JavaScript image and video upload
        • JavaScript image transformations
        • JavaScript video transformations
      • jQuery SDK
        • jQuery integration overview
        • jQuery image and video upload
        • jQuery image transformations
        • jQuery video transformations
      • Angular SDK
        • Angular integration overview
        • Angular image and video upload
        • Angular image transformations
        • Angular video transformations
      • React SDK
        • React integration overview
        • React image and video upload
        • React image transformations
        • React video transformations
      • Vue.js SDK
        • Vue.js integration overview
        • Vue.js image and video upload
        • Vue.js image transformations
        • Vue.js video transformations
      • iOS SDK
        • iOS integration overview
        • iOS image and video upload
        • iOS image transformations
        • iOS video transformations
      • Android SDK
        • Android integration overview
        • Android image and video upload
        • Android image transformations
        • Android video transformations
      • Kotlin SDK (Beta)
        • Kotlin media transformations (Beta)
      • Community-developed libraries
        • Gatsby
        • Gridsome
        • Laravel
        • NuxtJS
    • Add-ons
      • Adobe Photoshop Lightroom
      • 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 Object-Aware Cropping
      • 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
      • MetaDefender Anti-Malware Protection
      • 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
    • Platforms
      • Adobe Creative Cloud Connector
      • Magento Extension
        • Magento product catalog API
      • Salesforce Commerce Cloud Cartridges
        • Page Designer Cartridge
          • Custom integration
        • Site Cartridge
      • WordPress Plugin
      • Zapier Integration
        • Example: Cloudinary-Shopify Zap
      • Third-party-developed integrations
        • Contentful App
Login
sign up for free
  • Documentation
  • References
  • Metadata API

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.

Tip
It's also possible to create and manage structured metadata fields in the Manage Structured Metadata page of the Cloudinary console. For details, see Structured metadata management in the Digital Asset Management Guide.

On this page:

  • Generic structure of a metadata field
  • Validating data
  • Datasource values

Generic structure of a metadata field

Copy to clipboard
{
    "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_ids 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_ids, 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
  • less_than
  • strlen
  • and

greater_than validation

Relevant for integer and date types:

Copy to clipboard
{
    "type": "greater_than",
    "value": <value_by_type>,
    "equals": <boolean>
}
Property Type Description
value String The value for validation.
equals Boolean Whether to check if greater than or equals. Default: false

For example:

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

less_than validation

Relevant for integer and date types:

Copy to clipboard
{
    "type": "less_than",
    "value": <value_by_type>,
    "equals": <boolean>
}
Property Type Description
value String The value for validation.
equals Boolean Whether to check if less than or equals. Default: false

For example:

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

strlen validation

Relevant only for string types:

Copy to clipboard
{
    "type": "strlen",
    "min": <positive integer>,
    "max": <positive integer>
}
Property Type Description
min Integer The minimum string length. Default: 0
max Integer The maximum string length. Default: 1024

Note
Either min or max must be given, supplying both is optional.

For example:

Copy to clipboard
"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:

Copy to clipboard
{
    "type": "and",
    "rules": [ <validation_object>, <validation_object>, … ]
}
Property Type Description
validation_object Object One of the other validations above: greater_than, less_than or strlen

For example:

Copy to clipboard
"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.

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

Each datasource_entry defines a single possible value for the field:

Copy to clipboard
{
    "external_id": <string>,
    "value": <string>,
    "state": "active" | "inactive"
}
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:

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

✔️ 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:

  • Search API reference
  • Provisioning API reference
Cloudinary Logo - White
Products
  • Programmable Media
  • DAM
  • Dynamic Video
  • Demos
  • Pricing
  • Roadmap
  • FAQ
Solutions
  • Why Cloudinary
  • E-commerce and Retail
  • Media and Entertainment
  • Travel and Hospitality
  • Nonprofit
  • Our Customers
  • Resource Library
Developers
  • Getting Started
  • Documentation
  • SDK
  • Add-ons
  • Cookbook
Company
  • About Us
  • Customers
  • Partners
  • Events
  • Careers
  • Newsroom
  • Blog
  • Brand Assets
  • Trust
Contact Us
  • Technical Support
  • Contact Sales
  • Education and 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

© 2021 Cloudinary. All rights reserved.