Skip to main content
Framed content
Config schemas can only be created via the CLI. This is a deliberate design choice—we believe schemas should live in a Git repository. This allows them to be versioned alongside the code that uses them and encourages better software development practices. Ideally, schemas are versioned in the same repository as the code that uses them. However, this is not a requirement. You may use any Git repository to house your schemas.

​
Prerequisites

To create a schema, the following prerequisites must be met:
  1. CLI installed - install the Miru CLI on your development machine and authenticate using the login command
  2. Config type created - create a config type to house the schema

​
Define the schema

Begin by defining your schema using a supported schema language. You can find example schemas in our getting-started repository. If you’re not sure which language to use, we recommend starting with JSON Schema — it’s the most widely used and easiest to get started with. To get started quickly, feel free to use an empty schema, which considers all config instances as valid. 
$schema: "https://json-schema.org/draft/2020-12/schema"

​
Annotations

Annotations are a convenient way to store schema metadata with your schema. Most annotations are optional, but some are required for Miru to process the schema correctly.
​
config type
required
The config type is a required annotation that identifies the config type to which a schema belongs. Below is the syntax for annotating your schema with the config type slug.
x-miru-config-type: "{config-type-slug}"
Examples: mobility, safety-features, perception
​
instance file path
The instance file path is the file system location that config instances (for this schema) are deployed to relative to the /srv/miru/config_instances directory.This annotation is optional and defaults to {config-type-slug}.json, which deploys config instances to /srv/miru/config_instances/{config-type-slug}.json on a given device.
x-miru-instance-filepath: "{instance-file-path}"
Examples: /v1/mobility.json, /safety.json, configs/perception.json

​
Git metadata

When pushing a schema to Miru, the CLI captures Git metadata from the local Git repository from which the CLI is run:
  • Commit SHA - the SHA of the current commit that the schema is defined in
  • Origin URL - the remote URL of the Git repository
  • File path - the path to the schema file within the repo
This metadata is then made available in the dashboard for each schema, making it easy to trace the origin of each schema. While Git metadata is captured from the local Git repository, only origin URLs from the following providers are supported:
  • GitHub
  • GitLab
  • Bitbucket
If your Git repository is hosted on a different provider, please reach out to

​
Requirements

To be able to capture Git metadata, schemas must meet the following requirements when uploading from the CLI:
  • The schema must be defined in a local Git repository
  • The Git repository must have a remote URL (e.g., GitHub, GitLab, Bitbucket).
  • The schema’s latest changes must be committed to the Git repository before pushing to Miru (cannot be dirty or unstaged)
Git metadata is not optional. If a schema does not meet these requirements, the CLI will return an error and fail to push the schema.

​
Push the schema

Once you’ve defined a schema and committed it to Git, you’re ready to push it to Miru via the CLI. To push a schema, replace {path/to/schema.yaml} with the actual path to the schema file. 
miru schema push {path/to/schema.yaml}

​
New schemas

If the schema content does not match any existing schemas, a new schema is created.
command
$ miru schema push communication.yaml
🔍 Collecting Git Info...
    commit: df48a89cc19751f84cfbdc5908896235418a6719
    origin: [email protected]:miruml/getting-started.git
    file path: jsonschema/communication.yaml
    message: refactor: drop watchdog timeout from 5s to 2s

🟢 communication SCH-9Kd4W successfully created
    language: jsonschema
    format: yaml
    created: Nov 20, 2025 at 3:45 PM PST
    instance file path: /communication.json

​
Existing schemas

If a schema with equivalent content already exists, a new schema is not created. However, the Git metadata is attached to the existing schema.
output
$ miru schema push communication.yaml
🔍 Collecting Git Info...
    commit: df48a89cc19751f84cfbdc5908896235418a6719
    origin: [email protected]:miruml/getting-started.git
    file path: jsonschema/communication.yaml
    message: refactor: drop watchdog timeout from 5s to 2s

🟡 communication SCH-9Kd4W already exists
    language: jsonschema
    format: yaml
    created: Nov 20, 2025 at 3:45 PM PST
    instance file path: /communication.json