Overview

A config schema defines the structure, types, and constraints of a config instance. It serves as a contract between code and configuration, ensuring that config instances are valid before being deployed to devices.

Properties

string

The schema language used to define the schema.Allowed values:

jsonschema
cue
opaque

enum

The file format used to define the schema.Config schemas support the following file formats:

Language	Schema Formats	Instance Formats
JSON Schema	JSON, YAML	JSON, YAML
CUE	CUE	JSON, YAML
Opaque	JSON, YAML	JSON, YAML, XML, Text

Note that a schema’s format does not need to match the format of the config instance it validates. For example, a YAML-formatted JSON Schema can validate a JSON-formatted config instance.Allowed values:

cue
json
yaml

string

The raw schema definition, written in the specified schema language.The exact contents of a schema file is preserved in Miru, including any comments, whitespace, and formatting.

string

A hash of the canonicalized schema content.Digests are computed by converting schemas to a canonical format—a format that ignores whitespace, comments, and other non-semantic differences—and then hashing the result. This is useful for comparing schemas and detecting duplicates.Examples: sha256:45YeoJJ2btBnAKQztAEXEjHsqyyQfC1z1Mw3LLM4xMUy

InstanceSlot[]

The valid file system destinations that config instances for this schema are written to.Typically a schema defines only a single required slot. However, schemas may define several instance slots when the same validation applies to several different config instances in a release.See Instance slots for fields, constraints, and default behavior.

string

The file format that config instances (for this schema) are deployed as on the device.Consult the file formats section below for the supported formats for each schema language.Examples: json, yaml, xml, text

Config Type

The config type to which the schema belongs.Examples: Mobility, Safety Features, Perception

Schema languages

Config schemas are defined using a schema language—a formal language for describing the structure, constraints, and data types of a configuration. Miru supports:

JSON Schema (draft 2020-12)
CUE
Opaque (metadata-only schemas that regard all config instances as valid)

For more information on schema languages, visit the languages section of this guide.

File formats

Config schemas support the following file formats:

Language	Schema Formats	Instance Formats
JSON Schema	JSON, YAML	JSON, YAML
CUE	CUE	JSON, YAML
Opaque	JSON, YAML	JSON, YAML, XML, Text

Note that a schema’s format does not need to match the format of the config instance it validates. For example, a YAML-formatted JSON Schema can validate a JSON-formatted config instance.

Instance slots

An instance slot defines one or more valid config instances that are valid for a given schema. Instance slots are defined as an annotation within the schema itself. 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 four 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

Schema 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

Immutability

Config schemas are immutable. A schema is created once as part of a release and never edited in place. To change what a config type accepts, you must create a new schema, release it, and deploy it to your devices.

Git provenance

Schemas are defined as files in your Git repository and created by releasing them via the CLI. Each schema records the Git commits it was released from — the commit itself and the schema file’s paths relative to the repository root — so any schema in Miru can be traced back to the exact lines that defined it.

Validating instances

The primary purpose of schemas is to validate config instances. Let’s look at a simple example to see this in action. The following is a toy schema written in JSON Schema.

JSON Schema

$schema: "https://json-schema.org/draft/2020-12/schema"
title: Mobility
type: object
properties:
    max_linear_speed_mps:
        type: number
        minimum: 0.1
        maximum: 5.0
        default: 1.2
    max_angular_speed_radps:
        type: number
        minimum: 0.1
        maximum: 3.0
        default: 1.0
    obstacle_avoidance_enabled:
        type: boolean
        default: true
    navigation_mode:
        type: string
        enum: [conservative, balanced, aggressive]
        default: balanced
    telemetry:
        type: object
        properties:
        upload_interval_sec:
            type: integer
            minimum: 10
            maximum: 300
            default: 60
        heartbeat_interval_sec:
            type: integer
            minimum: 1
            maximum: 60
            default: 10
        required:
        - upload_interval_sec
        - heartbeat_interval_sec
required:
- max_linear_speed_mps
- max_angular_speed_radps
- obstacle_avoidance_enabled
- navigation_mode
- telemetry

The schema defines what constitutes a valid config instance in several different ways:

Names the available properties
Organizes the configuration structure, placing some properties at the root while nesting other properties into logical groups
Gives each property a type, such as number, boolean, etc.
Constrains the values of each property—minimums, maximums, enumerations, etc.
Supplies default values to properties where appropriate

Most of these constraints are optional, and many features of JSON Schema are omitted here, but this gives you a flavor of what schemas are capable of. Say we are deploying the following config instance.

Unbeknownst to us, the max_angular_speed_radps field exceeds the maximum allowed value of 3.0. Luckily, before deployment to the device, the config instance is validated against the schema, throwing the following error:

Identifying the issue, we correct the max_angular_speed_radps field to use the maximum allowed value of 3.0 and deploy the config instance to the device.

This time, the config instance successfully validates against the schema and is deployed to the device. Although simple in concept, schemas are a powerful tool for preventing typos, misconfigurations, and other preventable errors.

Empty schemas

While schemas provide significant value in production deployments, defining one from scratch can be a considerable undertaking. Many teams find it best to begin with an empty schema—one that accepts any configuration—and gradually add constraints. This approach allows you to define the most highly valued constraints first and progressively transition to stricter and stricter schemas as needed. Below are the empty schemas for JSON Schema and CUE, respectively.

$schema: "https://json-schema.org/draft/2020-12/schema"

{}

Welcome

Primitives

Config Management

Data Uploads

Developers

Administration

Properties

Schema languages

File formats

Instance slots

Schema annotations

Immutability

Git provenance

Validating instances

Empty schemas

​Properties

​Schema languages

​File formats

​Instance slots

​Schema annotations

​Immutability

​Git provenance

​Validating instances

​Empty schemas

Properties

Schema languages

File formats

Instance slots

Schema annotations

Immutability

Git provenance

Validating instances

Empty schemas