Edit

meta.json reference

The meta.json file is a JSON file that describes your module. It contains information about the module, such as its name, version, and the resource models it provides.

The meta.json file has the following fields:

Name	Type	Inclusion	Description
`module_id`	string	Required	The module ID, which includes either the module namespace or organization ID, followed by its name: `<namespace>:<module-name>` or `<org-id>:<module-name>`. Caution The `module_id` uniquely identifies your module. Do not change the `module_id`.
`visibility`	string	Required	Whether the module is accessible only to members of your organization (`private`), or visible to all Viam users (`public`). You can later make a private module public using the `viam module update` command. Once you make a module public, you can only change it back to private if it is not configured on any machines outside of your organization.
`url`	string	Required for cloud build	The URL of the GitHub repository containing the source code of the module. Cloud build will fail if you do not provide this. Optional for local modules.
`description`	string	Required	The description of your module and what it provides.
`models`	array	Optional	An array of objects describing the models provided by your module. You must provide at least one model in the models array or one application in the applications array. For more information see Models.
`entrypoint`	string	Optional	The name of the file that starts your module. This can be a compiled executable or a script. If you are providing your module as a single file to the `upload` command, provide the path to that single file. If you are providing a directory containing your module to the `upload` command, provide the path to the entry point file contained within that directory. Required if you are shipping a model.
`build`	object	Optional	An object containing the command to run to build your module, as well as optional fields for the path to your dependency setup script, the target architectures to build for, and the path to your built module. Use with the Viam CLI build subcommand. `"setup"` (Optional): Command to run for setting up the build environment. `"build"` (Required): Command to run to build the module tarball. `"path"` (Optional): Path to the built module tarball. `"arch"` (Required): Array of architectures to build for. For more information see Supported platforms for automatic updates. `"darwin_deps"` (Required): Array of homebrew dependencies for Darwin builds. Explicitly pass `[]` for empty. Default: `["go", "pkg-config", "nlopt-static", "x264", "jpeg-turbo", "ffmpeg"]`
`markdown_link`	string	Optional	Link to the documentation (README) for this module. Viam uses this to render your README on your module's page in the registry.
`$schema`	string	Optional	Enables VS Code hover and autocomplete as you edit your module code. Auto-generated when you run `viam module generate` or `viam module create`. Has no impact on the module's function.
`applications`	array	Optional	Objects that provide information about the applications provided by the module. For more information see Applications.

Models

Each modular resource has two associated triplets: an API namespace triplet to indicate which API it implements, and a model namespace triplet to uniquely identify the modular resource model.

API namespace triplet and model namespace triplet examples

The rand:yahboom:arm model and the rand:yahboom:gripper model use the module name (and matching repo name) yahboom. The models implement the rdk:component:arm and the rdk:component:gripper APIs to support the Yahboom DOFBOT arm and gripper, respectively:
```
{
    "api": "rdk:component:arm",
    "model": "rand:yahboom:arm"
},
{
    "api": "rdk:component:gripper",
    "model": "rand:yahboom:gripper"
}
```
The viam-labs:audioout:pygame model uses the repository name audioout. It implements the custom API viam-labs:service:audioout:
```
{
  "api": "viam-labs:service:audioout",
  "model": "viam-labs:audioout:pygame"
}
```

Each model object contains the following fields:

Property	Type	Description
`"api"`	string	A colon-delimited triplet `namespace:type:subtype` identifying the component or service API. Example: `rdk:component:motor`. See valid API identifiers for more information.
`"model"`	string	A unique colon-delimited triplet `namespace:module-name:model-name` identifying the resource model. If you are publishing a public module (`"visibility": "public"`), the namespace of your model must match the namespace of your organization. See valid model identifiers for more information.
`"short_description"`	string	Include a short description of the hardware the model supports for usage in the search bar when adding a resource.
`"markdown_link"`	string	Include a `markdown_link` to the section of the README containing configuration information about each model. The relevant section gets displayed alongside the configuration panel when configuring the model in the web UI. Example: `"README.md#configure-your-meteo_pm-sensor"`.

Valid model identifiers

The model namespace triplet uniquely identifies a resource model. It uses the format: namespace:module-name:model-name, where:

namespace is the namespace of your organization, which you can find or create on your organization settings page.
For example, if your organization uses the acme namespace, your models must all begin with acme, like acme:module-name:mybase. If you do not intend to upload your module to the registry, you do not need to use your organization’s namespace as your model’s namespace.
The viam namespace is reserved for models provided by Viam.
module-name is the name of your module. Your module-name should describe the common functionality provided across the model or models provided by that module. Many people also choose to use the module name as the name of the code repository (GitHub repo) that houses the module code.
model-name is the name of the new resource model that your module will provide.

For example, if your organization namespace is acme, and you have written a new base implementation named mybase which you have implemented with a module named my-custom-base-module, you would use the namespace acme:my-custom-base-module:mybase for your model.

Requirements:

Your model triplet must be all-lowercase.
Your model triplet may only use alphanumeric (a-z and 0-9), hyphen (-), and underscore (_) characters.

Valid API identifiers

Each component or service API has a unique identifier in the form of a colon-delimited triplet, the API namespace triplet.

The API namespace triplet is the same for all built-in and modular models that implement a given API. For example, every motor model built into Viam, as well as every custom motor model provided by a module, all use the same API namespace triplet rdk:component:motor to indicate that they implement the motor API.

The three pieces of the API namespace triplet are:

Component
Service

namespace: rdk
type: component
api: any one of these component proto files, for example motor if you are creating a new motor model

namespace: rdk
type: service
api: any one of these service proto files, for example vision if you are creating a new vision service model

Applications

The applications field is an array of application objects with the following properties:

Property	Type	Description
`name`	string	The name of your application, which is part of the application’s URL (`name_publicnamespace.viamapplications.com`). For more information on valid names see Valid application identifiers.
`type`	string	The type of application: `"single_machine"` or `"multi_machine"`. Whether the application can access and operate one machine or multiple machines.
`entrypoint`	string	The path to the HTML entry point for your application. The `entrypoint` field specifies the path to your application’s entry point. For example: `“dist/index.html”`: Static content rooted at the `dist` directory `“dist/foo.html”`: Static content rooted at the `dist` directory, with `foo.html` as the entry point `“dist/"`: Static content rooted at the `dist` directory (assumes `dist/index.html` exists) `“dist/bar/foo.html”`: Static content rooted at `dist/bar` with `foo.html` as the entry point
`fragmentIds`	[]string	Specify the fragment or fragments that a machine must contain to be selectable from the machine picker screen. Only for single machine applications.
`logoPath`	string	The URL or the relative path to the logo to display on the machine picker screen for a single machine application.
`customizations`	object	Override the branding heading and subheading to display on the authentication screen for single machine applications: `heading`: Override the heading. May not be longer than 60 characters. `subheading` Override the subheading. May not be longer than 256 characters. Example: `{ "heading": "Air monitoring dashboard", "subheading": "Sign in and select your devices to view your air quality metrics in a dashboard" }`.

Valid application identifiers

If your module includes a Viam application, you need to define the application name in your module’s meta.json file. Application names have the following requirements:

Application names must be all-lowercase.
Application names may only use alphanumeric (a-z and 0-9) and hyphen (-) characters.
Application names may not start or end with a hyphen.
Application names must be unique within your organization’s namespace.

The URL for accessing your Viam app will contain your application name:

https://app-name_your-public-namespace.viamapps.com

For example, if your organization namespace is acme and your application name is dashboard, your application will be accessible at:

https://dashboard_acme.viamapps.com

Create a namespace for your organization

When uploading modules to the Viam Registry, you must set a unique namespace for your organization to associate your module with.

To create a new namespace for your organization, click on the org’s Settings in the top right of the navigation bar, then click the Set a public namespace button. Enter a name or use the suggested name for your namespace, and then click Set namespace. A namespace may only contain letters, numbers, and the dash (-) character.

Update a namespace for your organization

You can change your organization’s namespace on your organization settings page:

Navigate to your organization settings page using the dropdown in the upper right corner of the web UI.
Click the Rename button next to your current namespace.
Enter the new namespace name in the field that appears.
Click Rename to confirm the change.
For each module your organization owns, update the module code and meta.json to reflect the new namespace.
(Recommended) Update the model field in the configuration of any machines that use the module to use the new namespace. Machine configurations that reference the old namespace will continue to work, but we recommend updating them to use the new namespace to avoid confusion.

When you rename a namespace, Viam reserves the old namespace for backwards compatibility and you cannot reuse it.

Was this page helpful?

Glad to hear it! If you have any other feedback please let us know:

We're sorry about that. To help us improve, please tell us what we can do better:

Thank you!