There are three types of metadata that can be stored with your assets: structured metadata, contextual metadata, and tags. These types of metadata are useful for searching assets based on a value or field value pair, or as a method of marking assets for a particular purpose in your end-user application.

For example, you can set up a "Specials" page in your web store to display all assets where the structured metadata sale field is set to campaign-A. Or, all assets that show scarves can be auto-tagged with a value scarf to be displayed on your web store accordingly.

This enables users from your creative, marketing, or sales teams to decide which assets get which field values or tags, while you use custom metadata API methods to implement the application side.

Custom metadata types

The following sections describe each of the three types of custom metadata that can be stored with each asset in your product environment and explains the differences between them:

• Tags: individual text values that can be assigned to specific assets (up to 1000 tags allowed per asset).
• Contextual metadata: custom key-value pairs that you can assign to individual assets.
• Structured metadata: custom fields are defined, along with data types and validations, at a global level, and are added to all assets in the product environment. You assign their values per asset.

The following table compares the three types of metadata:

Custom metadata comparison table

	Tags	Contextual Metadata	Structured Metadata
Value types	All values are unvalidated, free-text strings.	All fields are unvalidated, free-text strings.	Each metadata field is defined with a specific type (string, number, single or multi-select list, or date). The field can optionally be set with validation requirements (which can limit the values allowed in the field to, for example, a numeric range or number of characters). Fields may also have conditional metadata rules applied that can change elements of their definition based on selections in other fields.
Scope	Values are added individually to each asset, or to several assets in bulk, manually or through automatic tagging.	Fields and values are added individually to each asset.	Fields are defined for the entire product environment. The values are set individually for each asset.
Created by	Fields and values can be added by any user with write-level permissions for a particular asset. Your assets can also be automatically tagged using a Cloudinary add-on during upload or update using AI image recognition and categorization capabilities.	Fields and values can be added by any user with write-level permissions for a particular asset.	Fields are created and managed globally either by an Assets administrator in the Manage Structured Metadata page, or by a developer via the metadata API. Any user with write-level permissions for a particular asset can add or edit the field values.
API methods	- Add, remove, and replace tags: tags methods of the Upload API. - Add tags: upload method of the Upload API. - View and add tags: resources methods of the Admin API. - Replace tags: explicit method of the Upload API. - View tags: tags method of the Admin API.	- Add fields and values: context method of the Upload API. - Add values: upload and explicit methods of the Upload API. - View and add tags: resources method of the Admin API.	- Manage fields: metadata_fields method of the Admin API. - Set field values: metadata, upload and explicit methods of the Upload API. - View and set field values: resources methods of the Admin API.
Benefits	This metadata type enables assets to be automatically classified and tagged, which is especially useful when managing assets in bulk.	This metadata type gives more control and flexibility to individual users.	This metadata type enables more standardization across the organization.