Vocabulary
Overview
This page is a reference of key terminology used in Miru. If this is your first time using Miru, please read the core concepts guide and refer back to this page as needed.
Config Instance
A config instance is a particular instantiation of parameters used to alter the behavior of code.
Config instances are typically stored as JSON or YAML files (or potentially in a database somewhere), which applications parse into a structured format for consumption. The following YAML file defines a config instance for controlling a robot’s motion.
Config Schema
A config schema defines the constraints on a config instance.
Miru uses JSON Schema, a popular open-source configuration language for defining the valid fields, types, and values in a JSON or YAML file. Below is an example of a config schema written in JSON Schema.
Miru only supports JSON Schema, which is widely used and has code generation for many languages. However, support for other configuration languages is coming soon. Here are some popular ones.
Config Type
A config type represents the parameters responsible for configuring a particular aspect of an application through time.
For instance, an application may have a Mobility
config type that controls the motion of a robot. The Mobility
config type goes through many iterations—parameters
are added or deprecated (creating new config schemas for the config type) and given different
values (creating new config instances for the config type).
The Mobility
config type is not a particular instantiation of parameters or a particular specification of constraints. Instead, it is the parameters responsible for configuring the motion of a robot at any point in an application’s lifecycle.
Device
A device is the machine to which config instances are deployed. This could be an NVIDIA Jetson, Raspberry Pi, industrial PC, or any other machine powering a robot.
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 devices based on their hardware:
Raspberry Pi 4 Model B
NVIDIA Jetson Orin Nano
NVIDIA Jetson Orin AGX
An environment
tag type could group devices based on their stage of development:
Dev
QA
Beta
Stable
An accelerometer
tag type could define a tag for each accelerometer:
Accelerometer 1
Accelerometer 2
Accelerometer 3
Accelerometer 4
A device’s accelerometer tag reflects the specific accelerometer in use by the device, which may change as accelerometers are replaced or upgraded.
Devices may be “tagged” with any number of tags as long as they are from unique tag types.
Metadata
Metadata is data stored about a particular tag.
Suppose a 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, say robots powered by 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.
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 config instances that are deployed to devices. Metadata schemas only describe what constitutes valid metadata, effectively structuring the metadata stored for devices and tags.
Override
An override references tag metadata to “override” the default configuration values of a config schema. Here is a hardware
override example.
The default values in the config 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 config schema, only a subset of the config schema fields. However, it cannot specify fields not present in the config schema.
Overrides 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
features.backflip: false
since the NVIDIA Jetson Orin Nano
tag has
supports_jump: true
supports_spin: true
supports_backflip: false
This would override the default values in the config schema, changing features.spin
from false
to true
.
Overrides are hierarchically evaluated to determine the config instance for a particular device. The device’s tags determine the specific values referenced by overrides.
Combining tags with overrides provides a flexible method for rendering configuration data unique to each device that is assured to conform to a given config schema.