Schema system

The TEN framework uses a schema system to define and validate data structures throughout the runtime environment. Schemas provide type definitions for extension properties and messages. The schema system offers the following key benefits:

Type safety - Prevents runtime errors by validating data types before processing
Data consistency - Ensures all extensions interpret data structures identically
Clear contracts - Provides explicit interface definitions between components
Automatic validation - Validates data at runtime without manual checking
Cross-language compatibility - Maintains consistent data handling across C++, Go, and Python extensions

TEN schemas differ from standard JSON Schema - they define metadata specific to the TEN runtime's type system and validation requirements, using JSON only as the representation format. Schemas are defined in manifest files and applied automatically when extensions exchange data or access properties.

Schema design principles

The TEN framework schema system follows three core design principles that ensure consistency and prevent conflicts across all schema definitions.

Object principle The schema for every field in the TEN framework must be defined as an object. This ensures a structured and consistent format across all schema definitions.

_5{ _5 "foo": { _5 "type": "int8" _5 } _5}

Incorrect format:

_3{ _3 "foo": "int8" _3}
Metadata-only principle The schema defines only metadata, not actual data values. This separation ensures that the schema remains a template for validation and does not mix with data content.
Conflict prevention principle In any JSON level containing a TEN schema, all fields must be user-defined, except for reserved fields like ten. This prevents conflicts between user-defined fields and system-defined fields.

Example with user-defined fields:

_8{ _8 "user_timeout": { _8 "type": "int32" _8 }, _8 "custom_setting": { _8 "type": "string" _8 } _8}

Example with reserved ten field:

_11{ _11 "ten": { _11 "framework_metadata": {} _11 }, _11 "user_timeout": { _11 "type": "int32" _11 }, _11 "custom_setting": { _11 "type": "string" _11 } _11}

Schema syntax and formatting

All TEN schemas follow consistent formatting rules:

Object structure: Each field definition must be an object with a type property
Nested properties: Objects use properties to define their field schemas
Array items: Arrays use items to define the schema for their elements
Type specification: The type field specifies the data type using TEN framework type names

The schema structure directly mirrors the data it describes, making it intuitive to understand the relationship between schema definitions and actual data values.

Schema types and structure

The TEN framework supports both primitive and complex data types in schema definitions, allowing you to describe simple values as well as structured data.

Primitive types

The TEN framework provides fundamental data types that correspond to common programming language primitives:

Numeric types:

int8, int16, int32, int64 - Signed integers of various sizes
uint8, uint16, uint32, uint64 - Unsigned integers of various sizes
float32, float64 - Single and double precision floating-point numbers

Other primitive types:

string - Unicode character sequences
bool - Binary true/false values
buf - Sequences of 8-bit unsigned bytes
ptr - Pointers to memory addresses

Primitive type schema syntax:

{
  "timeout": {
    "type": "int32"
  },
  "username": {
    "type": "string"
  },
  "enabled": {
    "type": "bool"
  }
}

Complex types

Complex types enable structured data representation for more sophisticated use cases.

Object type represents key-value pairs with string keys:

_16{ _16 "config": { _16 "type": "object", _16 "properties": { _16 "host": { _16 "type": "string" _16 }, _16 "port": { _16 "type": "int32" _16 }, _16 "ssl_enabled": { _16 "type": "bool" _16 } _16 } _16 } _16}
Array type represents collections of elements with the same type:

_8{ _8 "servers": { _8 "type": "array", _8 "items": { _8 "type": "string" _8 } _8 } _8}

Manifest schema integration

The manifest.json file serves as the central location where all schema definitions come together to create a complete extension interface specification.

Complete manifest structure

The manifest file integrates all schema definitions into a single, comprehensive structure that defines your extension's complete interface. A complete manifest includes package metadata, dependencies, and API schemas for all supported message types.

For example, here's a complete manifest structure:

{
 "type": "extension",
 "name": "media_processor",
 "version": "1.2.0",
 "dependencies": [
   {
     "type": "system",
     "name": "ten_runtime",
     "version": "1.0.0"
   }
 ],
 "api": {
   "property": {
     "max_concurrent_jobs": {
       "type": "int32"
     },
     "output_quality": {
       "type": "string"
     },
     "processing_config": {
       "type": "object",
       "properties": {
         "enable_gpu": {
           "type": "bool"
         },
         "memory_limit_mb": {
           "type": "int32"
         }
       }
     }
   },
   "cmd_in": [
     {
       "name": "start_processing",
       "property": {
         "input_file": {
           "type": "string"
         },
         "output_format": {
           "type": "string"
         }
       },
       "result": {
         "property": {
           "job_id": {
             "type": "string"
           },
           "estimated_duration": {
             "type": "int32"
           }
         }
       }
     }
   ],
   "cmd_out": [],
   "data_in": [
     {
       "name": "progress_update",
       "property": {
         "job_id": {
           "type": "string"
         },
         "percentage": {
           "type": "int8"
         }
       }
     }
   ],
   "data_out": [],
   "video_frame_in": [],
   "video_frame_out": [],
   "audio_frame_in": [],
   "audio_frame_out": []
 }
}

Combining schemas in manifest.json

When combining different schema types in your manifest, organize them by their purpose and message direction to create a clear and maintainable extension interface.

Organization principles:

Properties - Define extension configuration schemas in api.property
Commands - Separate incoming (cmd_in) and outgoing (cmd_out) command schemas
Data messages - Separate incoming (data_in) and outgoing (data_out) data schemas
Media frames - Define video and audio frame schemas for specialized processing

Schema relationships: The schemas work together to create a complete extension interface. Property schemas define configuration, while message schemas define communication protocols. The TEN runtime uses these schemas collectively to validate all data flowing through your extension.

Schema validation in practice

The TEN runtime applies schema validation automatically at key points during extension lifecycle and message processing.

Validation occurs during:

Extension initialization - Property values from property.json are validated against property schemas
Message routing - Incoming messages are validated against their corresponding schemas before delivery
Runtime property updates - Property changes via API calls are validated against schemas
Message sending - Outgoing messages are validated before transmission to ensure compatibility

Property schemas

Property schemas define the structure and types for extension configuration data stored in property.json files. These schemas enable type validation and ensure consistent property handling across your TEN application.

Property schemas are defined in the api.property section of your manifest file. Each property name maps to a schema definition that describes its expected type and structure.

For example, given this property data:

{
  "database_config": {
    "host": "localhost",
    "port": 5432,
    "credentials": {
      "username": "admin",
      "password": "secret123"
    }
  }
}

The corresponding TEN property schema definition is as follows:

{
  "api": {
    "property": {
      "database_config": {
        "type": "object",
        "properties": {
          "host": {
            "type": "string"
          },
          "port": {
            "type": "int32"
          },
          "credentials": {
            "type": "object",
            "properties": {
              "username": {
                "type": "string"
              },
              "password": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}

The TEN runtime validates property data against this schema to ensure type safety and structural correctness.

This sample schema ensures that:

host must be a string value
port must be a 32-bit integer
credentials must be an object containing string values for username and password

Command schemas

Command schemas define the structure and types for command messages exchanged between extensions. These schemas enable type validation for both command parameters and their expected results, ensuring consistent communication across your TEN application.

Command schemas are defined in the api.cmd_in and api.cmd_out sections of your manifest file. Each command includes a name, property schema for input parameters, and a result schema for the expected response.

For example, given this command message:

{
  "ten": {
    "name": "process_file",
    "seq_id": "123"
  },
  "file_path": "/data/input.txt",
  "compression_level": 5,
  "options": {
    "preserve_metadata": true,
    "output_format": "zip"
  }
}

The corresponding TEN command schema definition is as follows:

{
  "api": {
    "cmd_in": [
      {
        "name": "process_file",
        "property": {
          "file_path": {
            "type": "string"
          },
          "compression_level": {
            "type": "int8"
          },
          "options": {
            "type": "object",
            "properties": {
              "preserve_metadata": {
                "type": "bool"
              },
              "output_format": {
                "type": "string"
              }
            }
          }
        },
        "result": {
          "property": {
            "output_path": {
              "type": "string"
            },
            "file_size": {
              "type": "int64"
            },
            "success": {
              "type": "bool"
            }
          }
        }
      }
    ]
  }
}

The TEN runtime validates command data against this schema to ensure type safety and structural correctness.

info

The TEN framework allows you to exclude the ten field from your schema definition, as it is reserved and defined by the runtime.

This command schema ensures that:

file_path must be a string value
compression_level must be an 8-bit integer
options must be an object containing a boolean preserve_metadata and string output_format
The command result must include a string output_path, 64-bit integer file_size, and boolean success

Data, video frame, and audio frame schemas

The process for defining schemas for data, video frames, and audio frames is similar to that for commands but without the result field.

Next steps

Start implementing schemas in your extensions:

Define property schemas for your extension configuration in manifest.json
Create message schemas for commands and data exchanges between extensions
Test schema validation by providing invalid data during development to ensure your schemas work correctly
Review the Type System documentation for detailed information about supported data types and conversion rules

Schemas provide the foundation for type-safe, reliable communication in your TEN applications. Start with simple property schemas and gradually add message schemas as your extension interfaces become more complex.

Was this helpful?