> ## Documentation Index
> Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt
> Use this file to discover all available pages before exploring further.

# Conditional metadata rules


> **INFO**: This feature is available only to Cloudinary customers on an [Enterprise plan](https://cloudinary.com/pricing#pricing-enterprise).

## 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'. 
1. Selecting 'R&D' for the **Team** metadata field enables the **Role** metadata field with values such as 'QA', 'Devops' or 'Backend'.
1. 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:

```
GET https://api.cloudinary.com/v1_1/demo/metadata_rules
```

The API uses **Basic Authentication** over secure HTTP. Your Cloudinary **API Key** and **API Secret** (which can be found on the [API Keys](https://console.cloudinary.com/app/settings/api-keys) page of your Cloudinary Console Settings) 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:

```
curl https://<API_KEY>:<API_SECRET>@api.cloudinary.com/v1_1/<CLOUD_NAME>/metadata_rules
```

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.

The table below provides a quick summary of the methods available for the Admin API `metadata_rules` endpoint. See the [Admin API](admin_api#metadata_rules) documentation for detailed information on the following [Metadata rules methods](admin_api#metadata_rules), as well as detailed information on the [Metadata rule structure](admin_api#metadata_rule_structure).

Method | Description
---|---
GET<code class="code-method">/metadata\_rules | [Returns an index of all metadata rules.](admin_api#get_metadata_rules)
POST<code class="code-method">/metadata\_rules | [Creates a new metadata rule definition.](admin_api#create_a_metadata_rule)
PUT<code class="code-method">/metadata\_rules/:external\_id | [Updates an existing metadata rule definition.](admin_api#update_a_metadata_rule_by_id)  
DELETE<code class="code-method">/metadata\_rules/:external\_id | [Deletes a metadata rule by external ID.](admin_api#delete_a_metadata_rule_by_id)

## 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](#condition_structure) + [result](#result_structure)
 

### Condition structure

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

```json
{
  metadata_field_id: <string>,
  populated: <boolean>,
  includes: [<string>, <string>, … ],  
  equals: <string> or array of <strings> // array is for SET metadata fields only
}
```

> **NOTE**: For details on all the parameters, see the [Condition structure](admin_api#condition_structure) reference.

For example:

```json
{
  and: [
    { metadata_field_id: category_id, populated: true },
    { metadata_field_id: date_id, populated: false },
    { 
      or: [
        { metadata_field_id: role_id, includes: ["ext_1"] },
        { metadata_field_id: team_id, includes: ["ext_3", "ext_4"] },
      ]
    }
  ]
}
    // OR
{ metadata_field_id: role_id, populated: true }
```

### Result structure

The result options are applied to the metadata field when the [condition](#condition_structure) is met. The syntax is specified as follows:

```json
{
  enable: <boolean>,
  activate_values: <object>,  
  apply_value: <object>,
  set_mandatory: <boolean>
}
```

> **NOTE**: For details on all the parameters, see the [Result structure](admin_api#result_structure) reference.

For example:

```json
{enable: true}

{enable: true, apply_value: { value: "private"}}

{apply_value: { value: ["beige", "brown"], mode: "append"}}  // for a set field

{enable: true, activate_values: "all" } 

{enable: false, activate_values: { external_ids: nil, mode: "override" }}

{activate_values: { external_ids: ["israel_ext", "germany_ext"], mode: "override" }
```