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:

NameTypeInclusionDescription
module_idstringRequiredThe module ID, which includes either the module namespace or organization ID, followed by its name: <namespace>:<module-name> or <org-id>:<module-name>.
visibilitystringRequiredWhether 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.
urlstringRequired for cloud buildThe 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.
descriptionstringRequiredThe description of your module and what it provides.
modelsarrayOptional

Deprecated. An array of objects describing the models provided by your module. Specified models are ignored. Models are inferred from the module itself.

entrypointstringOptionalThe 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.
buildobjectOptionalAn 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_linkstringOptionalLink to the documentation (README) for this module. Viam uses this to render your README on your module's page in the registry.
$schemastringOptionalEnables 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.
applicationsarrayOptionalObjects that provide information about the applications provided by the module. For more information see Applications.

Applications

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

PropertyTypeDescription
namestringThe 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.
typestringThe type of application: "single_machine" or "multi_machine". Whether the application can access and operate one machine or multiple machines.
entrypointstringThe 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[]stringSpecify the fragment or fragments that a machine must contain to be selectable from the machine picker screen. Only for single machine applications.
logoPathstringThe URL or the relative path to the logo to display on the machine picker screen for a single machine application.
customizationsobjectOverride 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:

  1. Navigate to your organization settings page using the dropdown in the upper right corner of the web UI.
  2. Click the Rename button next to your current namespace.
  3. Enter the new namespace name in the field that appears.
  4. Click Rename to confirm the change.
  5. For each module your organization owns, update the module code and meta.json to reflect the new namespace.
  6. (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.

Previous

Update and manage modules

Next

Module configuration