Metadata System

The NYRA framework uses a consistent metadata system across multiple package types, including:

  • App

  • Extension Group

  • Extension

  • Protocol

  • System

This system allows each package to define and manage its own metadata for properties and message schemas.

Types of Metadata

Within NYRA, you’ll typically deal with two main forms of metadata:

Manifest

  • Location: Placed in the root directory of a NYRA package with the file name manifest.json.

  • Purpose:

    • Describes the package name and version, following semantic versioning (e.g., 1.0.0).

    • Defines NYRA Schemas for properties and message input/output.

    • Lists dependencies the package needs to function.

⚠️ Note on NYRA Schema

The NYRA schema in manifest.json isn’t a strict JSON schema. Instead, it captures metadata that the NYRA runtime uses to validate and process your package’s properties and messages. JSON is simply the format used to store and represent this data.

Property

  • Location: Typically in a file named property.json located in the root directory of the NYRA package.

  • Purpose:

    • Stores initial property values, which can be read and modified while the NYRA app is running.

    • These values are “live” and can change during execution, allowing dynamic updates to extension or app behavior.

Example of property.json

{
  "Darth Vader": "I am your father"
}

Manifest File

The manifest.json file acts as a blueprint for your NYRA package. It details the package metadata, property schemas, and message definitions.

Example of manifest.json

{
  "type": "app",
  "name": "default_app_cpp",
  "version": "1.0.0",
  "dependencies": [
    {
      "type": "system",
      "name": "nyra_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": []
  }
}

Purpose of the NYRA Schema in manifest.json

The NYRA schema helps the runtime:

  • Understand the types and structures of properties.

  • Validate input/output messages for commands, data flows, video, or audio frames.

  • Enforce consistency when sending messages between extensions.

When the NYRA Schema Is Used

  1. Property Validation

    • Whenever the NYRA runtime retrieves or updates a property, it checks the schema (if available) to make sure the property value is valid.

  2. Data Conversion

    • If you call the from_json API to convert a JSON payload into a message or property, the schema guides the runtime on how to parse the data.

  3. Compatibility Checks

    • The NYRA manager (or runtime) can verify whether a message from one extension can be received by another, ensuring the types match based on the schema.

Property Management

NYRA divides properties into two key categories:

  1. Message Properties

    • Associated with messages exchanged between extensions (commands, data payloads, audio/video frames, etc.).

    • Define the data or parameters each message contains.

  2. NYRA Package Properties

    • Associated with the package itself (e.g., an app or extension).

    • Used for configurations or runtime settings that shape how an extension or app behaves.

Manifest File

The manifest.json file acts as a blueprint for your NYRA package. It details the package metadata, property schemas, and message definitions.

Property system

Example of manifest.json

{
  "type": "app",
  "name": "default_app_cpp",
  "version": "1.0.0",
  "dependencies": [
    {
      "type": "system",
      "name": "nyra_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": []
  }
}

Purpose of the NYRA Schema in manifest.json

The NYRA schema helps the runtime:

  • Understand the types and structures of properties.

  • Validate input/output messages for commands, data flows, video, or audio frames.

  • Enforce consistency when sending messages between extensions.

When the NYRA Schema Is Used

  1. Property Validation

    • Whenever the NYRA runtime retrieves or updates a property, it checks the schema (if available) to make sure the property value is valid.

  2. Data Conversion

    • If you call the from_json API to convert a JSON payload into a message or property, the schema guides the runtime on how to parse the data.

  3. Compatibility Checks

    • The NYRA manager (or runtime) can verify whether a message from one extension can be received by another, ensuring the types match based on the schema.

Property Management

NYRA divides properties into two key categories:

  1. Message Properties

    • Associated with messages exchanged between extensions (commands, data payloads, audio/video frames, etc.).

    • Define the data or parameters each message contains.

  2. NYRA Package Properties

    • Associated with the package itself (e.g., an app or extension).

    • Used for configurations or runtime settings that shape how an extension or app behaves.

Property System

Defining NYRA Package Properties

In property.json, you define the properties that belong to a particular NYRA package:

{
  "prop_1_name": 0,
  "prop_2_name": "prop_2_value",
  "prop_3_name": [
    "hello",
    "prop_3_sub_value"
  ],
  "prop_4_name": {
    "prop_4_1_name": 1,
    "prop_4_2_name": "prop_4_sub_value"
  }
}

Each property name must be unique within this file.

NYRA Schema for Properties

  • If a property is defined in both property.json and the NYRA schema (inside manifest.json), the runtime validates and processes it according to the schema’s type rules.

  • If a property isn’t in the schema, the runtime falls back to default JSON handling, interpreting numbers as float64.

Property
NYRA Schema
Effect

Yes

Yes

The runtime validates the property based on the defined NYRA schema.

Yes

No

The runtime treats the property as a generic JSON value (e.g., float64).

Accessing Properties from an Extension

Extensions can use NYRA APIs to get or set properties at runtime. These APIs will apply schema validation (if present) and handle data conversions automatically.

Specifying Property Values in start_graph Command

When creating or starting a graph, you can pass property values for packages. The NYRA runtime processes them according to the manifest’s schema:

{
  "nodes": [
    {
      "type": "extension_group",
      "name": "foo_extension_group",
      "addon": "foo_extension_group_addon"
    },
    {
      "type": "extension",
      "name": "bar_extension",
      "extension_group": "foo_extension_group",
      "property": {
        "prop_1_name": 0,
        "prop_2_name": "prop_2_value",
        "prop_3_name": [
          "hello",
          "prop_3_sub_value"
        ],
        "prop_4_name": {
          "prop_4_1_name": 1,
          "prop_4_2_name": "prop_4_sub_value"
        }
      }
    }
  ]
}

This lets you dynamically set or override properties during graph initialization.

Accessing Properties from an Extension

The NYRA runtime provides APIs for extensions to access various properties.

Specifying Property Values in the start_graph Command

Property values related to the NYRA package can be specified in the start_graph command. The NYRA runtime processes these properties according to the NYRA schema (if defined) and stores them in the corresponding NYRA package instance.

Example of Property Specification in start_graph Command

{
  "nodes": [
    {
      "type": "extension_group",
      "name": "foo_extension_group",
      "addon": "foo_extension_group_addon"
    },
    {
      "type": "extension",
      "name": "bar_extension",
      "extension_group": "foo_extension_group",
      "property": {
        "prop_1_name": 0,
        "prop_2_name": "prop_2_value",
        "prop_3_name": [
          "hello",
          "prop_3_sub_value"
        ],
        "prop_4_name": {
          "prop_4_1_name": 1,
          "prop_4_2_name": "prop_4_sub_value"
        }
      }
    }
  ]
}

PreviousVersion SystemNextMessage System

Last updated