XSD Schema Design - Content Management

XSD Schema Design

Every Kaltura metadata XSD must include four base type definitions that the KMC and eSearch use for field type detection. Fields annotated with <appinfo> elements control how the KMC renders the metadata form and how eSearch indexes the values.

Kaltura-Native Field Types

KMC Type	XSD Type	Storage	KMC Control	eSearch Behavior
Text	`textType`	String	TextArea (single) / Textbox (multi)	Full-text search
Date	`dateType`	Unix timestamp (long)	DatePicker	Range queries
Entry Link	`objectType`	Entry/object ID string	LinkedEntries selector	ID match
Dropdown	`listType` + `enumeration`	String	Dropdown (single) / List (multi)	Exact match, KMC filter column

Date fields store Unix timestamps as longs (e.g., 1718409600 for 2024-06-15), not ISO date strings. This is the Kaltura-native convention used by KMC-NG for DatePicker rendering and eSearch range queries.

Base Type Definitions (Required)

Every Kaltura XSD must include these four type definitions at the bottom of the schema. The KMC uses these definitions to determine field types for form rendering:

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

Field Annotations (`<appinfo>`)

Annotations control how the KMC-NG renders each field and how eSearch indexes it:

<xsd:element name="Department" minOccurs="0">
  <xsd:annotation>
    <xsd:appinfo>
      <label>Department</label>
      <key>department</key>
      <searchable>true</searchable>
      <description>Owning department for this content</description>
      <hidden>false</hidden>
      <timeControl>false</timeControl>
    </xsd:appinfo>
  </xsd:annotation>
  <!-- field type definition follows -->
</xsd:element>

Annotation	Purpose	Default
`<label>`	Display name shown in KMC metadata form	Element name
`<key>`	Programmatic identifier used in custom integrations	Element name
`<searchable>`	When `true`, field is indexed in eSearch	`false`
`<description>`	Help text shown below the field in KMC	None
`<hidden>`	When `true`, field is hidden from KMC UI (for computed/internal fields)	`false`
`<timeControl>`	When `true`, enables time-based metadata entry (chapter markers in video timeline)	`false`

Applications building custom metadata forms read these annotations from the XSD (via metadataProfile.get or metadataProfile.serve) to auto-generate UI controls matching the KMC behavior.

Use listType with xsd:enumeration restrictions to create dropdown fields. This is the only field type available as a KMC filter column:

<xsd:element name="Priority" minOccurs="0">
  <xsd:annotation><xsd:appinfo>
    <label>Priority</label>
    <key>priority</key>
    <searchable>true</searchable>
  </xsd:appinfo></xsd:annotation>
  <xsd:simpleType>
    <xsd:restriction base="listType">
      <xsd:enumeration value="Low"/>
      <xsd:enumeration value="Medium"/>
      <xsd:enumeration value="High"/>
      <xsd:enumeration value="Critical"/>
    </xsd:restriction>
  </xsd:simpleType>
</xsd:element>

Multi-Value Fields

Use maxOccurs="unbounded" for repeatable fields:

<xsd:element name="Tag" type="textType" minOccurs="0" maxOccurs="unbounded">
  <xsd:annotation><xsd:appinfo>
    <label>Tags</label>
    <key>tags</key>
    <searchable>true</searchable>
  </xsd:appinfo></xsd:annotation>
</xsd:element>

In metadata XML, each value is a separate element:

<metadata>
  <Tag>api</Tag>
  <Tag>documentation</Tag>
  <Tag>v3</Tag>
</metadata>

Required vs Optional Fields

minOccurs="0" — optional field (recommended for most fields)
minOccurs="1" — required field (metadata XML must include this element)
maxOccurs="1" — single value (default)
maxOccurs="unbounded" — multi-value (repeatable)

Nested Elements

Use complexType with sequence for grouped fields:

<xsd:element name="ReviewInfo" minOccurs="0">
  <xsd:complexType>
    <xsd:sequence>
      <xsd:element name="ReviewedBy" type="textType" minOccurs="0"/>
      <xsd:element name="ReviewDate" type="dateType" minOccurs="0"/>
      <xsd:element name="ReviewStatus" minOccurs="0">
        <xsd:simpleType>
          <xsd:restriction base="listType">
            <xsd:enumeration value="Pending"/>
            <xsd:enumeration value="Approved"/>
            <xsd:enumeration value="Rejected"/>
          </xsd:restriction>
        </xsd:simpleType>
      </xsd:element>
    </xsd:sequence>
  </xsd:complexType>
</xsd:element>

Complete Schema Example

A production-ready schema with all field types, annotations, and required base type definitions:

<?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">
          <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:restriction>
          </xsd:simpleType>
        </xsd:element>

        <xsd:element name="ProjectName" type="textType" minOccurs="0">
          <xsd:annotation><xsd:appinfo>
            <label>Project Name</label>
            <key>project_name</key>
            <searchable>true</searchable>
          </xsd:appinfo></xsd:annotation>
        </xsd:element>

        <xsd:element name="DueDate" type="dateType" minOccurs="0">
          <xsd:annotation><xsd:appinfo>
            <label>Due Date</label>
            <key>due_date</key>
            <searchable>true</searchable>
          </xsd:appinfo></xsd:annotation>
        </xsd:element>

        <xsd:element name="RelatedEntry" type="objectType" minOccurs="0">
          <xsd:annotation><xsd:appinfo>
            <label>Related Entry</label>
            <key>related_entry</key>
            <searchable>true</searchable>
          </xsd:appinfo></xsd:annotation>
        </xsd:element>

        <xsd:element name="Tag" type="textType" minOccurs="0" maxOccurs="unbounded">
          <xsd:annotation><xsd:appinfo>
            <label>Tags</label>
            <key>tags</key>
            <searchable>true</searchable>
          </xsd:appinfo></xsd:annotation>
        </xsd:element>

        <xsd:element name="InternalNotes" type="textType" minOccurs="0">
          <xsd:annotation><xsd:appinfo>
            <label>Internal Notes</label>
            <key>internal_notes</key>
            <searchable>false</searchable>
            <hidden>true</hidden>
          </xsd:appinfo></xsd:annotation>
        </xsd:element>

      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>

  <!-- Required base type definitions for KMC compatibility -->
  <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>

Field Type Reference

KMC Type	XSD Pattern	Example Value	KMC Single Control	KMC Multi Control
Text	`type="textType"`	`"API Guides"`	TextAreaControl	TextboxControl
Date	`type="dateType"`	`1718409600` (Unix ts)	DatePickerControl	DatePickerControl
Entry Link	`type="objectType"`	`"0_abc123"`	LinkedEntriesControl	LinkedEntriesControl
Dropdown	`base="listType"` + `enumeration`	`"Engineering"`	DynamicDropdownControl	ListControl
Nested	`complexType` + `sequence`	(sub-elements)	DynamicSectionControl	—