---
title: Metadata Profiles (Schemas)
url: https://docs.kaltura.com/docs/rich-media-cms-apis/content-management/custom-metadata-metadata-profiles-schemas
---

## Metadata Profiles (Schemas)


A `KalturaMetadataProfile` defines a schema (XSD) that describes the structure of custom metadata. You create a profile once, then attach metadata instances conforming to that schema to individual objects (entries, categories, users, etc.).

### KalturaMetadataProfile Object

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Auto-generated profile ID (read-only) |
| `partnerId` | integer | Partner ID (read-only) |
| `name` | string | Display name |
| `systemName` | string | System-level identifier (machine-friendly, use for stable lookups) |
| `description` | string | Profile description |
| `status` | integer | `1` = ACTIVE, `2` = DEPRECATED, `3` = TRANSFORMING |
| `metadataObjectType` | integer | Object type this profile applies to (see 4.2) |
| `version` | integer | Profile version, incremented on XSD changes (read-only, filterable) |
| `xsd` | string | The XSD schema definition (read-only on get, set via add/update) |
| `xslt` | string | XSLT applied on every metadata add/update (read-only, set via `updateTransformationFromFile`) |
| `createMode` | integer | `1` = API, `2` = KMC, `3` = APP. KMC hides API-created profiles by default. |
| `disableReIndexing` | boolean | When true, prevents re-indexing of related objects on metadata changes |
| `createdAt` | integer | Unix timestamp (read-only) |
| `updatedAt` | integer | Unix timestamp (read-only) |
| `objectType` | string | Always `"KalturaMetadataProfile"` (read-only) |

### Metadata Object Types

| Value | Name | Description |
|-------|------|-------------|
| 1 | ENTRY | Media entries |
| 2 | CATEGORY | Categories |
| 3 | USER | Users |
| 4 | PARTNER | Partner-level (account-wide configuration) |
| 5 | DYNAMIC_OBJECT | Dynamic objects |
| 6 | USER_ENTRY | Per-user-per-entry records (quiz answers, watch progress) |

### Profile Status Values

| Value | Name | Description |
|-------|------|-------------|
| 1 | ACTIVE | Profile is active and can be used |
| 2 | DEPRECATED | Profile is deprecated |
| 3 | TRANSFORMING | Profile XSD update in progress, re-validating existing metadata |

### Create Profile (Inline XSD)


```
POST /service/metadata_metadataProfile/action/add
```



```bash
curl -X POST "$KALTURA_SERVICE_URL/service/metadata_metadataProfile/action/add" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "metadataProfile[objectType]=KalturaMetadataProfile" \
  -d "metadataProfile[name]=Content Classification" \
  -d "metadataProfile[systemName]=content_classification" \
  -d "metadataProfile[description]=Classify content by department and priority" \
  -d "metadataProfile[metadataObjectType]=1" \
  --data-urlencode 'xsdData=<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <xsd:element name="metadata">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element name="Department" minOccurs="0" maxOccurs="1">
          <xsd:annotation><xsd:appinfo>
            <label>Department</label>
            <key>department</key>
            <searchable>true</searchable>
            <description>Owning department</description>
          </xsd:appinfo></xsd:annotation>
          <xsd:simpleType>
            <xsd:restriction base="listType">
              <xsd:enumeration value="Engineering"/>
              <xsd:enumeration value="Marketing"/>
              <xsd:enumeration value="Sales"/>
              <xsd:enumeration value="Support"/>
            </xsd:restriction>
          </xsd:simpleType>
        </xsd:element>
        <xsd:element name="Project" type="textType" minOccurs="0" maxOccurs="1">
          <xsd:annotation><xsd:appinfo>
            <label>Project Name</label>
            <key>project</key>
            <searchable>true</searchable>
          </xsd:appinfo></xsd:annotation>
        </xsd:element>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
  <xsd:complexType name="textType">
    <xsd:simpleContent>
      <xsd:extension base="xsd:string"/>
    </xsd:simpleContent>
  </xsd:complexType>
  <xsd:complexType name="dateType">
    <xsd:simpleContent>
      <xsd:extension base="xsd:long"/>
    </xsd:simpleContent>
  </xsd:complexType>
  <xsd:complexType name="objectType">
    <xsd:simpleContent>
      <xsd:extension base="xsd:string"/>
    </xsd:simpleContent>
  </xsd:complexType>
  <xsd:simpleType name="listType">
    <xsd:restriction base="xsd:string"/>
  </xsd:simpleType>
</xsd:schema>'
```


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `metadataProfile[objectType]` | string | Yes | Always `KalturaMetadataProfile` |
| `metadataProfile[name]` | string | Yes | Display name for the profile |
| `metadataProfile[systemName]` | string | No | Machine-friendly identifier for stable lookups |
| `metadataProfile[description]` | string | No | Description |
| `metadataProfile[metadataObjectType]` | integer | Yes | `1`=ENTRY, `2`=CATEGORY, `3`=USER, `4`=PARTNER, `5`=DYNAMIC_OBJECT, `6`=USER_ENTRY |
| `xsdData` | string | Yes | XSD schema definition (inline, URL-encoded) |

**Response:** Full `KalturaMetadataProfile` object with generated `id`, `version=1`, and `status=1` (ACTIVE).

### Create Profile (File Upload)


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/metadata_metadataProfile/action/addFromFile" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "metadataProfile[objectType]=KalturaMetadataProfile" \
  -d "metadataProfile[name]=Content Classification" \
  -d "metadataProfile[systemName]=content_classification" \
  -d "metadataProfile[metadataObjectType]=1" \
  -F "xsdFile=@schema.xsd"
```


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `metadataProfile[objectType]` | string | Yes | Always `KalturaMetadataProfile` |
| `metadataProfile[name]` | string | Yes | Display name for the profile |
| `metadataProfile[systemName]` | string | No | Machine-friendly identifier for stable lookups |
| `metadataProfile[metadataObjectType]` | integer | Yes | `1`=ENTRY, `2`=CATEGORY, `3`=USER, `4`=PARTNER, `5`=DYNAMIC_OBJECT, `6`=USER_ENTRY |
| `xsdFile` | file | Yes | XSD schema file upload (multipart form field) |

Same as `add`, but the XSD is uploaded as a file instead of inline.

**Response:** Full `KalturaMetadataProfile` object with generated `id`, `version=1`, and `status=1` (ACTIVE).

### Get Profile


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/metadata_metadataProfile/action/get" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "id=$PROFILE_ID"
```


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Profile ID to retrieve |

Returns the full `KalturaMetadataProfile` object including the XSD content. Returns `METADATA_PROFILE_NOT_FOUND` if the profile does not exist.

**Response:**


```json
{
  "id": 12345,
  "partnerId": 123456,
  "name": "Content Classification",
  "systemName": "content_classification",
  "description": "Classify content by department and priority",
  "status": 1,
  "metadataObjectType": 1,
  "version": 1,
  "createMode": 1,
  "xsd": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><xsd:schema ...>...</xsd:schema>",
  "createdAt": 1718409600,
  "updatedAt": 1718409600,
  "objectType": "KalturaMetadataProfile"
}
```


### List Profiles


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/metadata_metadataProfile/action/list" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "filter[objectType]=KalturaMetadataProfileFilter" \
  -d "filter[systemNameEqual]=content_classification" \
  -d "filter[statusEqual]=1" \
  -d "filter[orderBy]=-createdAt" \
  -d "pager[pageSize]=50"
```


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `filter[objectType]` | string | Yes | Always `KalturaMetadataProfileFilter` |
| `filter[...]` | various | No | Filter fields (see table below) |
| `pager[pageSize]` | integer | No | Results per page (default 30, max 500) |
| `pager[pageIndex]` | integer | No | Page number, 1-based (default 1) |

**Filter fields (`KalturaMetadataProfileFilter`):**

| Field | Description |
|-------|-------------|
| `idEqual` / `idIn` | Exact profile ID or comma-separated IDs |
| `nameEqual` | Exact name match |
| `systemNameEqual` / `systemNameIn` | Exact system name or comma-separated system names |
| `metadataObjectTypeEqual` / `metadataObjectTypeIn` | Filter by object type (1=ENTRY, etc.) |
| `statusEqual` / `statusIn` | Filter by status (1=ACTIVE, 2=DEPRECATED, 3=TRANSFORMING) |
| `versionEqual` | Filter by profile version |
| `createModeEqual` / `createModeNotEqual` / `createModeIn` / `createModeNotIn` | Filter by creation mode (1=API, 2=KMC, 3=APP) |
| `createdAtGreaterThanOrEqual` / `createdAtLessThanOrEqual` | Date range filters (Unix timestamp) |
| `updatedAtGreaterThanOrEqual` / `updatedAtLessThanOrEqual` | Date range filters (Unix timestamp) |
| `orderBy` | `+createdAt`, `-createdAt`, `+updatedAt`, `-updatedAt` |

**Response:**


```json
{
  "totalCount": 1,
  "objects": [
    {
      "id": 12345,
      "name": "Content Classification",
      "systemName": "content_classification",
      "metadataObjectType": 1,
      "status": 1,
      "version": 1,
      "createMode": 1,
      "objectType": "KalturaMetadataProfile"
    }
  ],
  "objectType": "KalturaMetadataProfileListResponse"
}
```


### List Fields


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/metadata_metadataProfile/action/listFields" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "metadataProfileId=$PROFILE_ID"
```


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `metadataProfileId` | integer | Yes | Profile ID whose XSD fields to list |

Returns a parsed list of field definitions from the XSD. Useful for dynamically building forms or validating metadata XML without parsing XSD yourself.

**Response:**


```json
{
  "totalCount": 2,
  "objects": [
    {"fieldName": "Department", "objectType": "KalturaMetadataProfileField"},
    {"fieldName": "Project", "objectType": "KalturaMetadataProfileField"}
  ],
  "objectType": "KalturaMetadataProfileFieldListResponse"
}
```


### Update Profile


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/metadata_metadataProfile/action/update" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "id=$PROFILE_ID" \
  -d "metadataProfile[objectType]=KalturaMetadataProfile" \
  -d "metadataProfile[description]=Updated classification schema"
```


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Profile ID to update |
| `metadataProfile[objectType]` | string | Yes | Always `KalturaMetadataProfile` |
| `metadataProfile[name]` | string | No | Updated name |
| `metadataProfile[description]` | string | No | Updated description |
| `xsdData` | string | No | Updated XSD (triggers re-validation of existing metadata, increments version) |

Fields not included remain unchanged. Updating the XSD triggers the server to re-validate all existing metadata instances against the new schema. Keep schema changes backward-compatible (e.g., add new optional fields, widen enumerations) to pass re-validation successfully.

### Update XSD from File


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/metadata_metadataProfile/action/updateDefinitionFromFile" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "id=$PROFILE_ID" \
  -F "xsdFile=@updated_schema.xsd"
```


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Profile ID to update |
| `xsdFile` | file | Yes | Updated XSD schema file (multipart form field) |

Updates the profile XSD from a file upload. Triggers re-validation and transformation of all existing metadata instances. The profile `version` is incremented. During transformation, the profile status transitions to `TRANSFORMING` (3) and returns to `ACTIVE` (1) when complete.

### Revert Profile Version


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/metadata_metadataProfile/action/revert" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "id=$PROFILE_ID" \
  -d "toVersion=2"
```


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Profile ID |
| `toVersion` | integer | Yes | Version number to revert to |

Reverts the profile XSD to a previous version. All metadata instances are also reverted and re-validated against the restored schema. The `version` field is incremented (revert creates a new version, not a rollback).

### Serve XSD


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/metadata_metadataProfile/action/serve" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "id=$PROFILE_ID"
```


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Profile ID whose XSD to serve |

Returns the raw XSD content of the profile. Useful for programmatic schema validation or building dynamic forms from the schema definition.

### Delete Profile


```bash
curl -X POST "$KALTURA_SERVICE_URL/service/metadata_metadataProfile/action/delete" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "id=$PROFILE_ID"
```


| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | Yes | Profile ID to delete |

Deletes the profile and cascades to all metadata instances associated with it. This is a permanent operation — back up any needed data before deleting. Profiles of type `DYNAMIC_OBJECT` with active references return `METADATA_PROFILE_REFERENCE_EXISTS`.