​
Overview

This page defines the key terminology used in Miru and should be used as a quick reference. To quickly understand how Miru works we recommend you read through the core concepts and refer back to this page as needed.

​
Concrete Config

A concrete config is a particular instantiation of parameters used to alter the behavior of your code.

You’re probably storing concrete configs as JSON or YAML files (or potentially in a database somewhere), which your application parses into a structured format for consumption. The following YAML file defines a concrete config for controlling a robot’s motion.

speed: 10
features:
	spin: true
	jump: true
	backflip: false
accelerometer:
	id: acc_id_1
	offsets:
		x: 0.1
		y: 0.13
		z: -0.04
	scaling_factor:
		x: 1.0
		y: 1.02
		z: 0.99

​
Config Schema

A config schema defines the constraints on a concrete config.

Miru uses JSON Schema, a popular open-source configuration language for defining the valid fields, types, and values in a JSON or YAML file. Here is an example of a config schema written in JSON Schema.

$schema: "https://json-schema.org/draft/2020-12/schema"
type: object
properties:
  speed:
    type: integer
    minimum: 1
    default: 10
  features:
    type: object
    properties:
      spin:
        type: boolean
        default: true
      jump:
        type: boolean
        default: false
      backflip:
        type: boolean
        default: false
    required: [spin, jump, backflip]
  accelerometer:
    type: object
    properties:
      id:
        type: string
      offsets:
        type: object
        properties:
          x:
            type: number
          y:
            type: number
          z:
            type: number
        required: [x, y, z]
      scaling_factor:
        type: object
        properties:
          x:
            type: number
          y:
            type: number
          z:
            type: number
        required: [x, y, z]
    required: [id, offsets, scaling_factor]
required: [device_id, speed, features, accelerometer]

Miru officially supports JSON Schema, which is widely used and supports code generation in various languages. However, support for other configuration languages is coming soon. Here are some popular ones:

​
Config

A config represents the parameters responsible for configuring a particular aspect of your application through time.

For instance, your application may have a “motion control” config that controls the motion of your robot. The motion control config goes through many iterations—parameters are added or deprecated (creating new config schemas for the config) and given different values (creating new concrete configs for the config).

The motion control config is not a particular instantiation of parameters or a particular specification of constraints. Instead, it is the parameters responsible for configuring the motion of your robot at any point in your application’s lifecycle.

​
Client

A client is the machine to which concrete configs are deployed. This could be an NVIDIA Jetson, Raspberry Pi, industrial PC, or any other machine running your application.

​
Tag Types & Tags

A tag type is a group of related tags, while a tag is an instantiation of a tag type. Examples illustrate this best.

A hardware tag type could be used to group clients based on the hardware they run on: Raspberry Pi 4 Model B, NVIDIA Jetson Orin Nano, and NVIDIA Jetson Orin AGX.

An environment tag type could group clients based on the stage of development they are in: Dev, QA, Beta, and Stable.

An accelerometer tag type could define a tag for each accelerometer: Accelerometer 1, Accelerometer 2, Accelerometer 3, Accelerometer 4, etc. A client’s accelerometer tag would reflect the specific accelerometer in use by the client, which may change as accelerometers are replaced or upgraded.

As the name suggests, clients can be “tagged” with a particular tag.

​
Metadata

Metadata is data stored about a particular client or tag.

Maybe robots support certain features based on their hardware. This information can be stored as metadata for each tag in the hardware tag type.

For example, let’s say robots running the NVIDIA Jetson Orin Nano can support the jump and spin features but not the backflip feature. This information can be stored as metadata for the NVIDIA Jetson Orin Nano tag.

Similarly, clients may have unique data of their own, such as an ID. Miru allows the storage of arbitrary metadata for each client as well. Here we’re storing robot_id as metadata for a client.

​
Metadata Schema

A metadata schema defines the constraints on the metadata.

Metadata schemas are written in a configuration language like JSON Schema. The following JSON Schema is a plausible metadata schema for the robot_id metadata we showed above.

Miru requires every tag type to have a metadata schema describing what constitutes valid metadata for any tag of that tag type. For instance, the hardware tag type may have the following metadata schema to specify the features (jump, spin, backflip) supported by a given hardware.

Any tags of the hardware tag type can only store metadata that adheres to the hardware metadata schema.

Metadata schemas look eerily similar to config schemas but serve a different purpose. A metadata schema does not describe or enforce any constraints on the concrete configs that are deployed to clients. Metadata schemas only describe what constitutes valid metadata, effectively structuring the metadata stored for clients and tags.

​
Policy

A policy is a set of overrides that hierarchically evaluate to a concrete config. Policies have two components:

  1. A policy schema
  2. A hierarchical set of overrides

When deploying a concrete config to a client, it must adhere to a particular config schema. Config schemas refer to a policy that evaluates the client’s tags to determine the unique concrete config for deployment.

As an example, the config schema v8 of the Motion Control config uses the v4 Policy.

​
Policy Schema

A policy schema defines the constraints on the output of a policy’s evaluation.

As with a config schema or a metadata schema, policy schemas are written in a configuration language like JSON Schema. Below is an example.

$schema: "https://json-schema.org/draft/2020-12/schema"
type: object
properties:
  mode:
    type: string
	default: "normal"
  maxSpeed:
    type: integer
    minimum: 1
    default: 1
  features:
    type: object
    properties:
      spin:
        type: boolean
        default: true
      jump:
        type: boolean
        default: false
      backflip:
        type: boolean
        default: false
    required: [spin, jump, backflip]
  accelerometer:
    type: object
    properties:
      id:
        type: string
      offsets:
        type: object
        properties:
          x:
            type: number
          y:
            type: number
          z:
            type: number
        required: [x, y, z]
      scaling_factor:
        type: object
        properties:
          x:
            type: number
          y:
            type: number
          z:
            type: number
        required: [x, y, z]
    required: [id, offsets, scaling_factor]
required: [device_id, speed, features, accelerometer]

Although config schemas and policy schemas interact with each other, they serve different purposes.

Config schemas refer to a policy for evaluating a concrete config for a client. Config schemas can only refer to a policy if the config schema is compatible with the policy’s schema. Thus, the policy schema constrains the output of a policy to ensure it is compatible with any config schemas using the policy.

​
Override

The second part of a policy is its overrides. An override references tag metadata that “overrides” the current evaluation of a policy. Here is a hardware override example.

The default values in the policy schema are shown on the left. On the right is the hardware override, which references the supports_jump, supports_spin, and supports_backflip fields in the metadata schema for the hardware tag type.

Overrides are completely named and defined by you. An override does not need to specify all the fields in a policy schema, only a subset of the policy schema fields. However, it cannot specify fields not present in the policy schema.

Policies can only be evaluated given a particular tag. For instance, the features.jump, features.spin, and features.backflip fields in the hardware override reference the supports_jump, supports_spin, and supports_backflip fields in the metadata schema for the hardware tag type.

Given the NVIDIA Jetson Orin Nano tag, the hardware override would use features.jump: true, features.spin: true, and features.backflip: false since the NVIDIA Jetson Orin Nano tag has supports_jump: true, supports_spin: true, and supports_backflip: false. This would override the default values in the policy schema, changing features.spin from false to true.

Overrides are hierarchically evaluated to determine a concrete config for a client. The client’s tags determine the specific values referenced by overrides.

By combining tags with overrides, policies grant a flexible method to evaluate configuration data unique to each client that’s formatted according to a given config schema