Metadata Profiles (Schemas) - Content Management

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

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)

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

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:

{
  "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

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:

{
  "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

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:

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

Update Profile

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

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

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

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

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.