Required

Within the Nyra framework, requiredfields are restricted exclusively to message schemas. Currently, the properties of extensions are prohibited from containing required fields.

Implications:

This restriction allows schemas for the following message types to define required fields:

• cmd_in / cmd_out

• data_in / data_out

• audio_frame_in / audio_frame_out

• video_frame_in / video_frame_out

Placement of Required Fields:

For message schemas, required fields are permitted only in the following three contexts:

1. At the Property Level in <foo>_in / <foo>_out The required field is defined at the same level as the property it applies to.

2. Within the result Property in <foo>_in / <foo>_out Required fields can be specified as part of the result property.

3. Inside Nested Properties with type: object In cases where the property is an object, required fields can be included within nested structures.

Examples:

Illustrative examples of these three scenarios are provided below to demonstrate permissible configurations for required fields within message schemas.

{
  "api": {
    "cmd_in": [
      {
        "name": "foo",
        "property": {
          "a": {
            "type": "int8"
          },
          "b": {
            "type": "uint8"
          },
          "c": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "d": {
            "type": "object",
            "properties": {
              "e": {
                "type": "float32"
              }
            }
          },
          "exampleObject": {
            "type": "object",
            "properties": {
              "foo": {
                "type": "int32"
              },
              "bar": {
                "type": "string"
              }
            },
            "required": ["foo"]  // 3.
          }
        },
        "required": ["a", "b"],  // 1.
        "result": {
          "property": {
            "ccc": {
              "type": "buf"
            },
            "detail": {
              "type": "buf"
            }
          },
          "required": ["ccc"]  // 2.
        }
      }
    ]
  }
}

Use of required

When a Message is Sent from an Extension

When an extension invokes methods such as send_<foo>(msg_X) or return_result(result_Y), the framework validates msg_X or result_Yagainst their corresponding schemas. If any required fields specified in the schema are missing, the validation fails, resulting in a schema check error.

Error Handling Scenarios:

The framework handles schema check failures uniformly across three distinct scenarios, as detailed below:

1. Failure During send_<foo> for Nyra Commands

When send_<foo> transmits a Nyra command, and the schema validation fails:

• The method returns false immediately.

• If an error parameter is supplied, it will contain the error message detailing the schema validation failure.

2. Failure During return_result

When return_result encounters a schema validation failure:

• The method returns false.

• If an error parameter is supplied, it can include the error message related to the schema check failure.

3. Failure During send_<foo> for General Data Messages For general data-like messages (e.g., data, audio frame, or video frame) sent via send_<foo>, schema validation failures are handled as follows:

• The method returns false.

• If an error parameter is provided, it includes the error message corresponding to the failed schema validation

When a Message is Received by an Extension

Before nyra_runtime passes msg_X or result_Y to an extension's on_<foo>() handler or result processor, it performs a schema validation to ensure all required fields specified in the schema are present. If any required field is missing, the schema check fails, and the framework takes appropriate actions based on the type of incoming message.

1. Incoming Message as a Nyra Command

• If the message is a Nyra command and the schema validation fails:

  • nyra_runtime returns an error status_code to the preceding extension in the processing chain.

2. Incoming Message as a Nyra Command Result

If the message is a result of a Nyra command:

• nyra_runtime modifies the status_code of the result to indicate an error.

• Missing required fields are added to the message, with their values set to type-appropriate defaults.

3. Incoming Message as a Data-Like Message

For data-like messages such as data, audio frame, or video frame, when schema validation fails:

• nyra_runtime discards the message without further processing.

Behaviour of Graph Check

NYRA Manager has a function called Graph Check, which is used to verify the semantic correctness of a graph. The checks related to required fields are as follows:

1. For a connection, the required fields of the source must be a superset of the required fields of the destination.

2. If the same field name appears in both the source and destination required fields, their types must be compatible.