Annotations

Annotations are a convenient way to store metadata with your schemas. Most annotations are optional, but some are required for Miru to process the schemas correctly.

required

The config type is a required annotation that identifies the config type to which a schema belongs. Below is the syntax for annotating a schema with a config type slug.

x-miru-config-type: "{config-type-slug}"

@miru(config_type="{config-type-slug}")

config_type: "{config-type-slug}"

If the provided config type slug does not yet exist, it is automatically created. To edit a config type after creation, visit the config types documentation.Examples: mobility, communication, perception

The schema language declares the language that a schema is written in. This annotation applies to Opaque schemas only, and is required for them.JSON Schema and CUE schemas have no schema language annotation. Their language is inferred from the schema file itself, so a .cue file is read as CUE, and a .json or .yaml file is read as JSON Schema unless it declares itself opaque.

Opaque

language: "opaque"

Because an opaque schema is written as JSON or YAML — the same formats as a JSON Schema — this annotation is what distinguishes the two.

The instance file path is the absolute file system path where config instances for this schema are written on the device.

The Miru Agent ships with out-of-the-box access to /srv/miru. To deploy configs to a custom directory, please visit the File system access page.

This annotation is optional and defaults to /srv/miru/configs/{config-type-slug}.{instance-format}. To share the same schema amongst multiple config instances, declare instance slots instead.

x-miru-instance-filepath: "/srv/miru/configs/{config-type-slug}.json"

@miru(instance_filepath="/srv/miru/configs/{config-type-slug}.json")

instance_filepath: "/srv/miru/configs/{config-type-slug}.json"

Examples:

/srv/miru/configs/mobility.json
/home/myapp/configs/communication.yaml
/var/lib/myapp/configs/safety.yaml

Instance slots define one or more config instances that are valid for a given schema. Instead of maintaining a near-identical config type for each destination, declare several slots to allow multiple config instances to share a single schema.

A schema may declare an instance file path OR instance slots. Declaring both will error.

This annotation is optional. Omitting it will either use the instance file path annotation, or create a single slot with default values.

x-miru-instance-slots:
  - key: "left-arm"
    name: "Left Arm"
    filepath: "/srv/miru/configs/v1/left-arm.json"
    required: true
    description: "Config for the left arm controller"
  - key: "right-arm"
    name: "Right Arm"
    filepath: "/srv/miru/configs/v1/right-arm.json"
    required: false

@miru_instance_slot(
  key="left-arm", 
  name="Left Arm", 
  filepath="/srv/miru/configs/v1/left-arm.json", 
  required=true, 
  description="Config for the left arm controller",
)
@miru_instance_slot(
  key="right-arm", 
  name="Right Arm", 
  filepath="/srv/miru/configs/v1/right-arm.json", 
  required=false,
)

instance_slots:
  - key: "left-arm"
    name: "Left Arm"
    filepath: "/srv/miru/configs/v1/left-arm.json"
    required: true
    description: "Config for the left arm controller"
  - key: "right-arm"
    name: "Right Arm"
    filepath: "/srv/miru/configs/v1/right-arm.json"
    required: false

For more information about instance slots, visit the Instance slots section of the schemas documentation.

The instance format declares the format that config instances for this schema are deployed as on the device.Visit the File formats section of the schemas documentation to learn which formats are supported for each schema language.This annotation is optional and is inferred from the instance file path’s extension. Under the default instance file path of /srv/miru/configs/{config-type-slug}.json, the instance format therefore defaults to json.

x-miru-instance-format: "yaml"

@miru(instance_format="yaml")

instance_format: "xml"

Examples: json, yaml, xml, text

Instance slots

An instance slot defines one or more valid config instances that are valid for a given schema. Instance slots are declared with the instance slots annotation.

Multiple slots

Instance slots are primarily used to define a schema that serves multiple config instances with the same validation.

x-miru-config-type: "Motor Controller"
x-miru-instance-slots:
  - key: "motor-controller-1"
    name: "Motor Controller 1"
    filepath: "/srv/miru/configs/motor-controller-1.json"
    required: true
  - key: "motor-controller-2"
    name: "Motor Controller 2"
    filepath: "/srv/miru/configs/motor-controller-2.json"
    required: true
  - key: "motor-controller-3"
    name: "Motor Controller 3"
    filepath: "/srv/miru/configs/motor-controller-3.json"
    required: true
[...schema content...]

@miru(config_type="Motor Controller")
@miru_instance_slot(
  name="Motor Controller 1",
  key="motor-controller-1",
  filepath="/srv/miru/configs/motor-controller-1.json",
  required=true
)
@miru_instance_slot(
  name="Motor Controller 2",
  key="motor-controller-2",
  filepath="/srv/miru/configs/motor-controller-2.json",
  required=true,
)
@miru_instance_slot(
  name="Motor Controller 3",
  key="motor-controller-3",
  filepath="/srv/miru/configs/motor-controller-3.json",
  required=true,
)

[...schema content...]

config_type: "Motor Controller"
instance_slots:
  - key: "motor-controller-1"
    name: "Motor Controller 1"
    filepath: "/srv/miru/configs/motor-controller-1.json"
    required: true
  - key: "motor-controller-2"
    name: "Motor Controller 2"
    filepath: "/srv/miru/configs/motor-controller-2.json"
    required: true
  - key: "motor-controller-3"
    name: "Motor Controller 3"
    filepath: "/srv/miru/configs/motor-controller-3.json"
    required: true
[...schema content...]

A schema with multiple slots allows multiple config instances to be written to different destinations. This structure allows a motor-controller schema to serve three identical motor controllers. All instance slots share the exact same validation. So two files that need different validation belong to two config types, not to two slots of one schema.

Slot fields

Each instance slot is defined by the following fields:

string

required

An immutable, code-friendly identifier for the slot.Slot keys must be unique within a schema. Two slots cannot have the same key.Examples: motor-controller-1, motor-controller-2, motor-controller-3

string

required

A human-readable display name for the slot.Examples: Motor Controller 1, Motor Controller 2, Motor Controller 3

string

required

The absolute file system path where this slot’s config instance is written on the device.Slot file paths must be unique within a schema. Two slots cannot have the same file path.Examples: /srv/miru/configs/motor-controller-1.json, /srv/miru/configs/motor-controller-2.json, /srv/miru/configs/motor-controller-3.json

boolean

required

Whether a deployment must include a config instance for this slot or not.If true, a deployment must include a config instance for this slot. If false, a deployment may optionally include a config instance for this slot.Examples: true, false

string

An optional explanation of what the slot is for.Examples: The first motor controller, The second motor controller, The third motor controller

Welcome

Foundations

Config Management

Data Uploads

Developers

Administration

Annotations

Instance slots

Multiple slots

Slot fields

​Instance slots

​Multiple slots

​Slot fields

Instance slots

Multiple slots

Slot fields