Conditional metadata rules API reference

Overview

Conditional metadata rules allow you to set up dependencies and hierarchical relationships between structured metadata fields and field options. This allows you to:

• Enable/disable (show/hide) another metadata field based on the value selected for a metadata field.
• Activate options displayed for a particular metadata field based on the value specified in another field.
• Set the default metadata value in a particular field based on the value specified in another field.

Some popular use cases for conditional metadata include:

• High-level file type selection, for example: setting metadata fields on different types of content such as image, video and document.
• Support segmenting into categories, for example: product imagery vs lifestyle photography.
• Document asset usage rights, for example: stock imagery.
• Support large organizations with multiple metadata schemas.

For example, one of the metadata fields can include various category values for photos on a company intranet site, such as 'Employee', 'Conference', and 'Culture'. You could set up rules based on these values as follows:

1. Selecting 'Employee' in the Category metadata field enables (displays) the Team metadata field with values such as 'R&D', 'Product' or 'HR'.
2. Selecting 'R&D' for the Team metadata field enables the Role metadata field with values such as 'QA', 'Devops' or 'Backend'.
3. Selecting 'QA' for the Role metadata field enables the Name metadata field with the members of the QA team: 'John Smith' or 'Jane Kelly'. If Devops had been selected for the Role metadata field, then the Name field would be enabled with members of the Devops team: 'Paul Green' or 'Mary Rose'.

Metadata rules endpoint

The Metadata rules API endpoint is accessed using HTTPS. By default, the API endpoint uses the following format:

https://api.cloudinary.com/v1_1/:cloud_name/metadata_rules

For example, to list all Metadata rules in the 'demo' product environment:

The API uses Basic Authentication over secure HTTP. Your Cloudinary API Key and API Secret (which can be found on the Dashboard page of your Cloudinary console) are used for the authentication.

You can experiment with returning a list of the metadata rules in your own Cloudinary product environment by replacing the API_KEY, API_SECRET, and CLOUD_NAME in the cURL command below:

For most actions, request parameters are passed as JSON objects. The response is in a JSON snippet and includes information about the action that was performed.

Metadata rules methods

The Metadata rules methods enable you to manage the metadata rules available for your product environment.

Get metadata rules

Returns an index of all metadata rules (active and inactive) as an array of JSON objects. The rules are sorted by the dependent metadata field id, and then by their internal order (currently the order of insertion).

Syntax

GET /metadata_rules

Example

Sample response

Create a metadata rule

Creates a new metadata rule definition. Expects a JSON object which defines the rule.

Syntax

POST /metadata_rules

Required parameters

Example

When the category metadata field value is equal to 'employee', enable the team metadata field and activate all the available values:

Sample response

Update a metadata rule by id

Updates an existing metadata rule definition. Expects a JSON object which defines the updated rule.

Syntax

PUT /metadata_rules/:external_id

Required parameters

Optional parameters

Example

When the category metadata field value is equal to 'employee', enable the team metadata field and activate all the available values:

Sample response

Delete a metadata rule by id

Deletes a metadata rule definition. The rule should no longer be considered a valid candidate for all other endpoints (it will not show up in the list of rules, etc).

Syntax

DELETE /metadata_rules/:external_id

Required parameters

Example

Delete the metadata rule with an external_id of 'eae809b91168cf3877743713a9dd4b9428bb6f9c37385f6a4897f227b4b86d14':

Sample response

Metadata rule structure

Each metadata rule connects a specified metadata field with a condition to evaluate on a metadata payload (based on other fields' values), and then with a result to apply to the specified metadata field in the case that the condition is met.

Metadata rule = Metadata field + condition + result

Condition structure

The condition that must be met in order to activate the result. Each of the conditions must include the metadata_field_id (external_id of a metadata field) to evaluate, and the specific criteria to evaluate.

Syntax

Parameters

You can set multiple conditions by defining them as and conditions that must all be met for the result to be applied, or as or conditions where it is enough that one of the conditions is met.

Examples

Result structure

The result options are applied to the metadata field when the condition is met.

Syntax

Parameters

One or more of the following actions can be applied:

activate_values

The activate_values action can be set to either activate all the values available ("all") or you can specify an object detailing the list of available external_ids as an array of datasource values by their external_ids, and the mode to either 'override' the existing values or to 'append' them to the current values.

apply_value

The apply_value action is used to apply a specified value for the metadata field. For multi-select (set) fields you can apply multiple values by giving an array of datasource external_ids, and the mode to either apply them as the 'default' values or to 'append' them to the currently selected values.

Examples: