Metadata system

The TEN framework uses a metadata system to define, validate, and manage configuration data across all components in your application. The system applies consistently to all package types in the framework, namely:

App: Main application containers that orchestrate the overall system behavior
Extension: Individual functional components that implement specific features or capabilities
Extension Group: Collections of related extensions that work together as a coordinated unit
Protocol: Communication protocol handlers that manage data exchange between components
System: Core framework components that provide essential runtime services

The metadata system provides several key benefits:

Type safety and validation: Ensures data integrity by validating property types and values at runtime, preventing common configuration errors before they cause application failures.
Clear API definitions: Establishes standardized interfaces between components, making it easier to understand how different parts of your application communicate and what data they expect.
Runtime flexibility: Allows you to modify configuration settings while your application runs, enabling dynamic behavior changes without requiring restarts or redeployment.
Dependency management: Tracks relationships between components and their version requirements, ensuring compatibility and proper loading order.

The metadata system consists of two main files in each package:

manifest.json for structural definitions and schemas
property.json for runtime configuration values

Manifest File System

The manifest.json file serves as the primary metadata definition for each TEN package. Located in the package's root directory, it defines the package's core metadata and API specifications:

Package identification: Name and version following semantic versioning
Dependencies: Required packages and their version constraints
API schema definitions: Type definitions for properties and messages
- Property schemas: Data type specifications for package configuration
- Message schemas: Input/output message format definitions

The TEN schema in manifest.json provides metadata about the package's external API, enabling:

Property validation: Validates properties when the runtime gets/sets them
Data conversion: Converts JSON to TEN package or message properties using the from_json API
Compatibility checks: Verifies if messages can be routed between extensions according to the TEN schema

File structure and required fields

The manifest.json file contains the following main sections:

type: Package type: app, extension, extension_group, protocol, system
name: Unique package identifier
version: Semantic version number
dependencies: Array of required packages with version constraints
api: Complete API specification including properties and message definitions

Dependencies Section

Dependencies specify other packages required for this package to function properly. Each dependency includes:

"dependencies": [
  {
    "type": "system",
    "name": "ten_runtime", 
    "version": "1.0.0"
  }
]

API schema definitions

The api section defines the complete interface specification for the package, including:

property: Package property schemas with type definitions
cmd_in/cmd_out: Command message schemas for input and output
data_in/data_out: Data message schemas for input and output
video_frame_in/video_frame_out: Video frame message schemas
audio_frame_in/audio_frame_out: Audio frame message schemas

info

The TEN schema in manifest.json is not a JSON schema. It describes TEN value metadata that are central to the TEN runtime, while JSON serves only as a representation format.

Example manifest.json:

{
  "type": "app",
  "name": "default_app_cpp",
  "version": "1.0.0",
  "dependencies": [
    {
      "type": "system",
      "name": "ten_runtime",
      "version": "1.0.0"
    }
  ],
  "api": {
    "property": {
      "exampleInt8": {
        "type": "int8"
      },
      "exampleString": {
        "type": "string"
      }
    },
    "cmd_in": [
      {
        "name": "cmd_foo",
        "property": {
          "foo": {
            "type": "int8"
          },
          "bar": {
            "type": "string"
          }
        },
        "result": {
          "property": {
            "detail": {
              "type": "string"
            },
            "aaa": {
              "type": "int8"
            },
            "bbb": {
              "type": "string"
            }
          }
        }
      }
    ],
    "cmd_out": [],
    "data_in": [
      {
        "name": "data_foo",
        "property": {
          "foo": {
            "type": "int8"
          },
          "bar": {
            "type": "string"
          }
        }
      }
    ],
    "data_out": [],
    "video_frame_in": [],
    "video_frame_out": [],
    "audio_frame_in": [],
    "audio_frame_out": []
  }
}

Property File System

The property.json file, located in the package's root directory, contains runtime configuration values that the TEN framework can modify during execution. These properties:

Store configurable settings and parameters
Support runtime modification without restarting the application
Must conform to any schema definitions specified in the manifest file

The property system enables dynamic configuration management, allowing your TEN application to adapt its behavior based on runtime conditions or user preferences.

Property types

The TEN framework manages two distinct types of properties:

Message properties are associated with messages exchanged between extensions within the framework. These properties define specific data or parameters carried within a message, such as:
- Command parameters and arguments
- Data payloads and content
- Metadata for audio/video frames
- Custom message attributes
Package properties are associated with TEN packages themselves (extensions, apps, etc.). These properties define configuration or settings specific to a package, such as:
- Runtime behavior settings
- Initialization parameters
- Feature flags and options
- Connection and timeout values

Defining properties in property.json

The property.json file defines package properties using JSON format. Properties can include various data types and nested structures:

{
 "connection_timeout": 5000,
 "max_retries": 3,
 "debug_mode": false,
 "api_endpoint": "https://api.example.com",
 "nested_config": {
   "buffer_size": 1024,
   "compression_enabled": true
 },
 "array_values": ["option1", "option2", "option3"]
}

info

Each property name in the property.json file must be unique.

Property schema definitions

You can define TEN schemas for properties in the manifest.json file, enabling the TEN runtime to handle these properties more effectively. The runtime behavior depends on whether properties have corresponding schema definitions:

Property defined	Schema defined	Runtime behavior
Yes	Yes	Validates values against schema and enforces type checking
Yes	No	Uses default JSON handling (numbers become float64)

Property validation rules

When TEN schemas are defined for properties, the runtime validates:

Type compliance: Ensures property values match their declared types
Value constraints: Enforces any specified ranges or validation rules
Required properties: Verifies that mandatory properties are present
Format validation: Checks string formats, numeric ranges, and other constraints

Setting properties in `start_graph`

You can override default property values when starting a TEN application by specifying them in the start_graph command. The runtime processes these values according to their TEN schema definitions and applies them to the appropriate package instances:

{
  "nodes": [
    {
      "type": "extension_group",
      "name": "foo_extension_group",
      "addon": "foo_extension_group_addon"
    },
    {
      "type": "extension",
      "name": "bar_extension",
      "extension_group": "foo_extension_group",
      "property": {
        "connection_timeout": 3000,
        "debug_mode": true,
        "custom_setting": "override_value"
      }
    }
  ]
}

Was this helpful?