Smart Transcript
SmartTranscript v1.0 Schema Documentation
Overview
The SmartTranscript schema is a flexible data model for representing multi-channel conversations (including audio, chat, email, and video), capturing detailed transcript data, speaker details, timing, and rich semantic analysis. It enables developers and organizations to store, exchange, and analyze conversational data for applications in customer service, analytics, compliance, and research.
Top-Level Structure
A SmartTranscript object is a JSON object with the following required fields:
- schema_type:
"smart-transcript"(string, constant) - schema_version: (string, e.g.,
"v1.0") - smart_transcript_id: Unique identifier for this transcript instance (string, e.g., UUID)
- source_type: Describes the channel type; one of:
"audio","chat","email","video" - participants: Array of participant definitions
- messages: Array of utterances or messages
Optional top-level fields include:
- source: Name or ID of the source system (string or null, e.g.,
"zoom","call_center") - duration_seconds: Total conversation length in seconds (number or null)
- languages: Array of detected languages and probabilities
- metadata: Additional key-value metadata for the entire transcript (object)
Top-Level Properties
| Property | Type | Description | Required |
|---|---|---|---|
| schema_type | string (const) | Always "smart-transcript". Identifies the schema in use. | Yes |
| schema_version | string | Identifies schema version (e.g., "v1.0"). | Yes |
| smart_transcript_id | string | Unique transcript ID (UUID, hash, etc.). | Yes |
| source_type | string (enum) | Interaction type: "audio", "chat", "email", "video". | Yes |
| source | string or null | Name/ID of the source system (e.g., "zoom"). | No |
| duration_seconds | number or null | Total conversation duration in seconds. | No |
| languages | array of objects | List of detected languages and confidence scores. | No |
| metadata | object | Additional key-value metadata for the entire transcript | No |
| participants | array of objects | List of participants (required fields: participant_id, role). See below. | Yes |
| messages | array of objects | List of message/utterance objects. See below. | Yes |
Participants
Describes each entity involved in the conversation.
Participant Object
| Property | Type | Description | Required |
|---|---|---|---|
| participant_id | string | Unique participant identifier | Yes |
| role | string (enum) | "agent", "customer", "ivr", "system", "other" | Yes |
| name | string or null | Display name of participant | No |
| channel | string or null | Channel-specific ID (e.g., phone, chat handle) | No |
| metadata | object | Additional key-value metadata | No |
| external_id | string or null | Optional external system identifier (e.g., CRM ID) | No |
| talk_time_seconds | number or null | Total speaking time in seconds for this participant | No |
| word_count | integer or null | Total word count for this participant | No |
| first_appearance | number or null | Timestamp (in seconds from conversation start) of first appearance | No |
| talk_time_ratio | number or null | Proportion of total conversation time spoken by this participant (0–1) | No |
Messages
An array of messages, utterances, or turns in the conversation. Each entry captures what was said, by whom, when, and analytic information.
Message (Utterance) Object
| Property | Type | Description | Required |
|---|---|---|---|
| message_id | string | Unique ID for the message | Yes |
| participant_id | string | ID of the message sender (match participant) | Yes |
| language | string | Language code (ISO 639-1) of this message. Must be exactly 2 lowercase letters (e.g., "en", "es", "fr"). | Yes |
| timestamp_start | number | Start timestamp (seconds from start) | Yes |
| timestamp_end | number | End timestamp (seconds from start) | Yes |
| content | string | Raw transcript or body | Yes |
| metadata | object | Additional key-value metadata for the message | No |
| metrics | object | Automatic metrics for the message (see below) | No |
| analysis | object | Semantic, sentiment, emotion, and intent analysis | No |
| topic | string | Topic classification (e.g., "billing", "technical") | No |
| speech_act | string | Speech act type (e.g., "question", "greeting") | No |
| words | array or null | Optional array of word-level timing information (see below) | No |
Metrics Object
Captures statistics about the message.
| Metric | Type | Description |
|---|---|---|
| word_count | integer or null | Number of words |
| syllable_count | integer or null | Number of syllables |
| pause_count | integer or null | Detected pauses (audio only) |
| avg_word_time | number or null | Average duration per word (seconds/word) |
| max_word_time | number or null | Maximum duration of any word (seconds) |
Analysis Object
Rich semantic and affective analysis for the message.
| Property | Type | Allowed Values | Description |
|---|---|---|---|
| sentiment | string or null | "positive", "neutral", "negative", null | Sentiment polarity |
| emotion | string or null | "neutral", "happy", "sad", "angry", "fearful", "disgusted", "surprised", "empathetic", null | Primary detected emotion |
| tone | string or null | "neutral", "polite", "assertive", "friendly", "sarcastic", "professional", "calm", "confident", "formal", null | Communication tone/style |
| urgency | string or null | "low", "medium", "high", null | Urgency level |
| clarity | string or null | "clear", "unclear", null | Message clarity |
| intent | string or null | (user-defined, e.g., "question", "greeting", "request", "closing", null) | Communicative intent |
Words Array
Optional word-level timing information for the message. Each element in the array represents a single word or space with precise timing.
| Property | Type | Description |
|---|---|---|
| text | string | The text content of the word (may include spaces) |
| timestamp_start | number | Relative start time (in seconds) from the beginning of the recording |
| timestamp_end | number | Relative end time (in seconds) from the beginning of the recording |
Example
{
"schema_type": "smart-transcript",
"schema_version": "v1.0",
"smart_transcript_id": "7d4edbe4-12f3-4a53-b9fe-372f6aa89880",
"source_type": "audio",
"source": "call_center",
"duration_seconds": 85.2,
"languages": [
{"language": "en", "probability": 0.99}
],
"participants": [
{"participant_id": "p1", "role": "agent", "name": "Sam Lee"},
{"participant_id": "p2", "role": "customer", "name": "Alex Kim"}
],
"messages": [
{
"message_id": "m1",
"participant_id": "p1",
"language": "en",
"timestamp_start": 0.0,
"timestamp_end": 2.3,
"content": "Thank you for calling. How can I help you today?",
"metrics": {
"word_count": 10,
"syllable_count": 13,
"pause_count": 0,
"avg_word_time": 0.23,
"max_word_time": 0.30
},
"analysis": {
"sentiment": "neutral",
"emotion": "professional",
"tone": "polite",
"urgency": "low",
"clarity": "clear",
"intent": "greeting"
},
"topic": "general",
"speech_act": "greeting",
"words": [
{
"text": "Thank",
"timestamp_start": 0.0,
"timestamp_end": 0.15
},
{
"text": " ",
"timestamp_start": 0.15,
"timestamp_end": 0.18
},
{
"text": "you",
"timestamp_start": 0.18,
"timestamp_end": 0.25
}
]
}
]
}
Additional Information
- All objects are strict: unknown properties are not allowed.
- Timestamps use seconds from start (float/double).
- All string enums (for roles, sentiment, etc.) are case-sensitive and must match allowed values.
- Language codes must follow ISO 639-1 format: exactly 2 lowercase letters (e.g., "en", "es", "fr").
- Extensible: More analytic fields/topics may be added as new versions are published.
See the corresponding v1.0.json file for detailed validation rules (JSON Schema), including required, allowed, ranges, and formats.
Available Views
| View | Description | Projection |
|---|---|---|
one-liner | Single-line transcript identification | { id: smart_transcript_id, source_type: source_type, part... |
summary | Transcript overview with participants and metadata | { id: smart_transcript_id, source_type: source_type, titl... |
full | Complete transcript with all messages and analysis | @ |
Use the SDK to render views:
from ontopix_schemas import SchemaInstance
instance = SchemaInstance(data)
print(instance.view("one-liner"))
print(instance.view("summary"))
print(instance.view("full"))