---
title: XSD Schema Design
url: https://docs.kaltura.com/docs/rich-media-cms-apis/content-management/custom-metadata-xsd-schema-design
---

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


```xml
<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:


```xml
<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.

### Enum Fields (Dropdown)

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


```xml
<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:


```xml
<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:


```xml
<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:


```xml
<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
<?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 | — |