Application Schemas

This document describes schema files that you will write while developing applications.

Application schemas are the following three:

• Setting Schema: the schema of application configs to fit its operating environment (setting_schema.json)
• Data Schema: the schema of data sent as Act Log (data_schema.json)
• Manifesto: a description of resources needed at runtime

By creating act_settings.json you can test your data schema.

setting_schema.json

A Setting Schema defines a format of configurations within an application.

Applications can use files that conform to the schema using the environment variable ACT_SETTINGS_PATH. At the application start-up, ACT_SETTINGS_PATH is bound to the JSON file path, then it is accessed like an ordinary JSON file.

The setting schema specifies the JSON described above. You have to write it on setting_schema.json with the JSON Schema[^json schema]. For example, the following schema:

{
  "$schema": "https://actcast.io/schema/v7/setting_schema_schema.json",
  "type": "object",
  "properties": {
    "display": {
      "title": "display",
      "description": "output video to HDMI display",
      "type": "boolean",
      "default": false
    },
    "threshold": {
      "title": "probability threshold",
      "description": "notify when over this threshold",
      "type": "number",
      "default": 0.9,
      "minimum": 0.0,
      "maximum": 1.0
    }
  },
  "required": [],
  "propertyOrder": ["display", "threshold"]
}

is conformed by the following JSON:

{
  "display": true,
  "threshold": 0.7
}

This JSON will be passed to applications.

Items available in the setting schema

The following fields are available in the setting schema.

Write "https://actcast.io/schema/v7/setting_schema_schema.json" to $schema, "object" to type.

When propertyOrder is omitted, propertyOrder will be inserted when uploading to Actcast, in the order of appearance in properties.

properties

The following items are available in properties.

We recommend supplying title and default as far as possible, though they aren’t required.

descriptions

Write description in languages other than English in descriptions. Use language codes described in ISO 639-1 as property names and put the description in that language to values.

For example, the following value:

{
  "ja": "これはフィールドの説明です",
  "eo": "Ĉi tiu estas la ekspliko de la areno"
}

type

The following items are available in type:

x-ui-type

The following items are available in x-ui-type:

data_schema.json

The data schema describes the format of the output of your application.

The data schema is used in Casts. For example, they are used to realize behaviors like “When the confidence score is greater than 90%, POST the data to somewhere”. Each line of the output of Actcast applications must conform with the data schema. The strings printed to standard output will be transferred to Actcast as the Act Log.

You have to write the data schema to the file data_schema.json in JSON Schema.

For example, the following value:

{
  "$schema": "https://actcast.io/schema/v7/data_schema_schema.json",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "prob": {
        "title": "probability",
        "description": "matching score",
        "type": "number",
        "minimum": 0.0,
        "maximum": 1.0
      },
      "label": {
        "title": "label",
        "description": "the most matching class name",
        "type": "string"
      }
    },
    "required": ["prob", "label"]
  }
}

is conformed by the following JSON:

[
  {
    "prob": 0.3,
    "label": "cat"
  },
  {
    "prob": 0.7,
    "label": "dog"
  }
]

The application outputs JSON like this.

Items available in the data schema

The following fields are available in the data schema.

items

The following items are available in items

properties

The following items are available in properties.

In both items and properties, you can write the contents of items and properties recursively. descriptions accepts the same content as in Setting Schema.

type

The following items are available in type:

act_settings.json

The act_settings.json file in the current directory is automatically transferred and then used by the application. act_settings.json must follow the JSON schema file setting_schema.json.

The following command validates act_settings.json, setting_schema.json and data_schema.json.

$ actdk validate-json

actdk run also performs an equivalent validation.

manifesto/*.json

In the manifesto, you specify the resources needed at the application runtime. You can write different settings for each device. In that case, write them to different files.

At initialization, actdk generates some manifesto files. For example, default.json, as shown below, is the standard setting applied to all Raspberry Pis with VideoCore IV and allows access to the camera, VideoCore, and no special network.

{
  "boards": [
    "RSPi1A",
    "RSPi1B",
    "RSPi1APlus",
    "RSPi1BPlus",
    "RSPi2B",
    "RSPiAlpha",
    "RSPiCM1",
    "RSPi3B",
    "RSPiZero",
    "RSPiCM3",
    "RSPiZeroW",
    "RSPi3BPlus",
    "RSPi3APlus",
    "RSPiCM3Plus",
    "RSPiZero2W"
  ],
  "devices": [
    {
      "type": "camera",
      "device": ["/dev/video0"]
    },
    {
      "type": "videocore",
      "device": [
        "/dev/vcsm",
        "/dev/vcio",
        "/dev/vc-mem",
        "/dev/vchiq",
        "/dev/gpiomem"
      ]
    },
    {
      "type": "framebuffer",
      "device": ["/dev/fb0"]
    }
  ]
}

boards

You can specify the following boards in "boards":

At the application launch, the Actcast device agent checks the boards of manifesto/*.json files and determines which manifesto should be applied. So, elements of boards of manifesto/*.json must not be duplicated. (E.g., if both manifesto/a.json and manifesto/b.json contain RSPi4B in boards, it results in an error.)

devices

The "devices" can be a list of devices required by the application. The elements of the list are described as objects with the following fields.

The following device types can be specified for "type".

• "camera": Camera device
• "videocore": VideoCore
• "framebuffer": Frame buffer device
• "gpio": Device using GPIO pins
• "sound": Microphone or Speaker
• "other": Device that does not apply to the above.

The fact that required is true indicates that the device is required for the application to work. If a device is specified as required, the presence of the specified device file will be checked at the startup of the Act using that application. If the corresponding device file does not exist, the Act installation will fail to launch with an error.

Here is an example.

"devices": [
  {
    "type": "camera",
    "device": [
      "/dev/video0"
    ],
    "required": true
  }
]

As "/dev/video0" is set required:true in this settings, the presence of the device file will be checked at the startup of the Act.

networks

If you want to communicate with the outside, use the network manifesto, and your app will be able to communicate externally via the SOCKS proxy we provide.

See Network Manifesto for more detail.

allow_all_networks

This property can be specified when you want to allow the application to communicate with the outside without any restrictions.

The application will be able to communicate externally without going through the SOCKS proxy.

• When this setting is enabled, the settings of networks are ignored.
• Both TCP and UDP are allowed.

{
  "version": 2,
  "target_type": "raspberrypi-buster",
  "boards": ["RSPi4B"],
  "devices": [],
  "allow_all_networks": true
}

published_ports

This property can be listed ports to be published to the outside world. This enables the application to run a server and access it from the outside. To specify published ports, use an array of objects containing three fields: the port number used in the container (container_port), the port number actually used on the host side (host_port), and the protocol used (protocol).

• This property is only available when allow_all_networks is true.
• host_port must be a number between 1024 and 65535.
  • 8000 is unavailable because it is reserved by actsim
• protocol can be tcp, udp, and sctp.

{
  "version": 2,
  "target_type": "raspberrypi-buster",
  "boards": ["RSPi4B"],
  "devices": [],
  "allow_all_networks": true,
  "published_ports": [
    {
      "container_port": 8080,
      "host_port": 8080,
      "protocol": "tcp"
    }
  ]
}

New notation of manifesto/*.json

Actcast Agent version > 1.6.0 accepts the new notation of Manifesto (Manifesto V2). Major changes are:

• version field has been added
• target_type field has been added
• device file can be omitted in some types in the devices property.
• new device type of display has been added

You cannot use the former notation of Manifesto and Manifesto V2 at the same time.

Detailed notation is described below.

Example

{
  "version": 2,
  "target_type": "raspberrypi-buster",
  "boards": [
    "RSPi4B"
  ],
  "devices": [
    {"type": "camera"},
    {"type": "videocore"}
  ]
}

version

Input number in "version". This property is for future extension and it is always 2 in Manifesto V2.

target_type

Input the target type for the manifesto to apply to. Non-overwrapping multiple "target_type" can be specified for each board. This property is for future extention and it is always "raspberrypi-buster" in Manifesto V2.

boards

You can write the same "boards" as Manifesto V1.Combination of "targe_type" and "boards" cannot be duplicated.

devices

The "devices" can be a list of devices required by the application. The elements of the list are described as objects with the following fields.

The following device types can be specified for "type".

When "device" is omitted, the Actcast Agent determines files to mount based on "type".Those files mounted are notified to the application via Device handling in Applications.

The fact that required is true indicates that the device is required for the application to work. If a device is specified as required, the presence of device files will be checked at the startup of the Act using that application. If the corresponding device file does not exist, the Act installation will fail to launch with an error.

Here is an example.

"devices": [
  {
    "type": "camera",
    "required": true
  }
]

As required is set true in this settings, the presence of the appropriate device files will be checked at the startup of the Act.

networks

See Network Manifesto for more detail.