Module manifest (module.json) reference

Every section of a module's module.json: identity, permissions, tables and data migrations, agent, screens, services, schedules, outside systems and distribution.

Copy page for AIUpdated November 21, 2026

Every module has one module.json at the top of its folder. It is the module's description of itself: who it is, which version, what permissions it adds, which tables it needs, what its agent and screens are, and what it connects to. The platform reads it when the module is deployed and subscribed, and the module check validates it.

This page is the reference. Coding agents read the full version in the SDK as references/manifest-schema.md, and the how-to in skills/editing-manifest/SKILL.md (see The Module SDK).

A short, complete example

json
{
  "module_code": "VISITOR_LOG",
  "module_name": "Visitor Log",
  "module_description": "Sign visitors in and out at the front desk and see who is on site.",
  "version": "0.1.0",
  "distribution": {"visibility": "tenant_only", "source_access": "locked"},
  "api_base_path": "/api/v1/visitor_log",

  "permissions": [
    {"code": "VISITOR_LOG.READ", "label": "View visitors",
     "description": "See the visitor list", "default_roles": ["Admin"]},
    {"code": "VISITOR_LOG.WRITE", "label": "Sign visitors in and out",
     "description": "Add visitors and record when they leave", "default_roles": ["Admin"]}
  ],

  "data_tables": [
    {
      "name": "visits",
      "columns": [
        {"name": "id", "type": "UUID", "primary_key": true, "default": "gen_random_uuid()"},
        {"name": "visitor_name", "type": "VARCHAR(255)", "nullable": false},
        {"name": "company", "type": "VARCHAR(255)"},
        {"name": "host", "type": "VARCHAR(255)"},
        {"name": "signed_in_at", "type": "TIMESTAMPTZ", "default": "NOW()"},
        {"name": "signed_out_at", "type": "TIMESTAMPTZ"},
        {"name": "created_at", "type": "TIMESTAMPTZ", "default": "NOW()"},
        {"name": "updated_at", "type": "TIMESTAMPTZ", "default": "NOW()"}
      ],
      "indexes": [{"columns": ["signed_in_at"]}]
    }
  ],

  "seed_data": {
    "tables": {
      "visits": [
        {"visitor_name": "Sample Visitor", "company": "Sample Supplier", "host": "Front desk",
         "signed_in_at": {"$date": "-2d"}, "signed_out_at": {"$date": "-2d"}}
      ]
    }
  },

  "ui": {
    "icon": "icon.svg",
    "nav_items": [
      {"key": "today", "label": "Today", "page": "index.html", "permission": "VISITOR_LOG.READ"}
    ]
  },

  "tenant_settings": [
    {"key": "require_host", "type": "boolean", "default": true,
     "description": "Visitors must name who they are visiting"}
  ]
}

The one rule for tables: add, never drop or rename

When a new version is installed, the platform adds every new table and every new column. It never drops or renames a table or a column, and keeps every row.

  • New column: add it to the table's columns, nullable or with a default.
  • Never drop or rename. A renamed column comes back as a new, empty column, and the old data stays under the old name. Keep the old column.
  • Reshaping existing data (rename by copy, type change, filling a new column, splitting a table): add the new column or table, then move the data with data_migrations.
  • Removing a table or column from the manifest doesn't delete it. The data stays in your workspace's database, but your code can no longer reach it, so move what you need first.

Top-level fields

FieldRequiredWhat it isExample
module_codeYesPermanent identifier, UPPER_SNAKE_CASE, starts with a letter. Unique on the platform."VISITOR_LOG"
module_nameYesDisplay name."Visitor Log"
versionYesSemantic version. Raise it for every change."0.2.0"
distributionYesPrivate or Marketplace, and source terms.{"visibility": "tenant_only", "source_access": "locked"}
uiYes (ui.icon)Icon, sidebar pages, settings page, public pages.{"icon": "icon.svg"}
module_descriptionExpected (warning without)What the module does."Sign visitors in and out..."
api_base_pathNoWhere its routes are mounted. Defaults to /api/v1/<module code in lower case>."/api/v1/visitor_log"
permission_prefixNoPrefix for permission codes, when it should differ from module_code."VISITORS"
permissionsWhen it has routes or toolsThe permissions the module adds.see below
data_tablesNoTables created in your workspace's database.see below
data_migrationsNoOne-time steps that reshape existing data.see below
seed_dataNo (warning without, when there are tables)Sample rows a new subscriber sees.see below
storageNoFile folders for uploads.see below
aiNoThe module's agent, its tools and skills.see below
capabilitiesNoExtra privileges the module opts in to.{"allow_raw_sql": true}
runtimeNoPython packages the module needs.{"requirements": ["numpy==2.4.6"]}
servicesNoServices the module offers other modules.see below
service_dependenciesNoServices it calls on other modules.see below
record_sourcesNoRecords other modules can pick and read.see below
interface_dependenciesNo"Any module that provides projects" and similar.see below
uses_integrationsNoSystems the workspace has connected, such as Microsoft 365.see below
external_apisNoOutside services the module calls.see below
egressNoEvery outside host its code calls.["api.example.com"]
platform_servicesNoPaid platform services it uses, such as maps.[{"code": "MAPS", "why": "..."}]
eventsNoEvent names it owns and who may receive them.see below
schedulerNoSchedules and event-triggered agent runs.see below
messagesNoEmails it sends, as editable templates.see below
mobileNoHow it shows in the DV Mobile app.see below
tenant_settingsNoSimple settings each workspace can change.see below
reportingNoYour recorded reason for not publishing datasets.{"datasets": false, "reason": "..."}
marketplaceNoMarketplace card text.{"tagline": "...", "category": "Operations"}
bridgeNoTools it runs on your own computers through the Bridge. Needs approval by Data Visions.{"capabilities": ["metrics"], "tools": ["collect_metrics"]}
desktop_clientsNoData Visions programs the module offers for download.["VIDEO_BRIDGE"]

Don't use bridge_required: true or platform_bound_routes. Every module runs in its workspace's sandbox, and the upload refuses both. Don't rely on the integrations block (OAuth providers) yet: it doesn't work from a sandbox today.

permissions

json
{"code": "VISITOR_LOG.APPROVE", "label": "Approve visitors",
 "description": "Approve visitors waiting at the desk",
 "help": "For reception leads.", "default_roles": ["Admin"]}
KeyRequiredMeaning
codeYes<PREFIX>.ACTION. The prefix is permission_prefix, or module_code.
descriptionYesWhat it allows.
default_rolesYesWhich roles get it when a workspace subscribes. Use ["Admin"] for nearly everything, or [] for no one until an admin chooses.
label, helpNoThe plain name and the "when to grant it" line a Workspace Admin sees when building a role.
risk_levelNoFor example "high".

A workspace's only built-in role is Admin; admins create every other role. "Operator" and "Viewer" are still accepted in default_roles but give nothing. The platform adds <PREFIX>.REPORTS_VIEW and <PREFIX>.MANAGE_SETTINGS itself; don't declare them.

data_tables and columns

Each table is created in your workspace's own database when it subscribes.

KeyMeaning
nameTable name.
columnsList of columns. Every table needs a primary key.
indexesOptional: [{"columns": ["status", "created_at"]}], with "unique": true for a unique index.
Column keyMeaning
nameColumn name. Avoid reserved words such as user, order, type.
typeUUID, VARCHAR(N), TEXT, INTEGER, BIGINT, SMALLINT, DOUBLE PRECISION, NUMERIC, REAL, FLOAT, BOOLEAN, TIMESTAMPTZ, TIMESTAMP, DATE, TIME, JSONB, JSON, BYTEA, INET, CIDR, MACADDR, INTERVAL.
primary_keytrue for the key column.
nullablefalse for a required column.
defaultA default expression: gen_random_uuid(), NOW(), 'active'.
uniquetrue for unique values.
foreign_keyAnother table of this module, "visits(id)". Never another module's table.

Give every table id (UUID primary key), created_at and updated_at. Store uploaded files in storage and keep only a reference to the file in the table.

data_migrations

Ordered, one-time steps that reshape data already in use. Each workspace that installs the version runs each step once, in order, after the new columns and tables are added.

json
"data_migrations": [
  {"id": "0.3.0_fill_priority", "op": "fill", "table": "visits",
   "column": "priority", "value": 3, "description": "Existing visits get normal priority"},
  {"id": "0.3.0_status_words", "op": "copy_column", "table": "visits",
   "from": "state", "to": "status", "map": {"i": "in", "o": "out"}}
]
opWhat it doesKeys
fillSets an empty column to a valuetable, column, value, optional where
copy_columnCopies one column into another on the same table, converting the typetable, from, to, optional map, empty_as_null, where
copy_rowsCopies rows into another tablefrom_table, to_table, columns, key, optional where
serviceRuns a service your module declaresservice
  • Every step needs an id that starts with the version, such as 0.3.0_fill_priority.
  • Add new steps at the end. Never edit or remove a step a released version shipped.
  • Copy into a new column with no default, or existing rows are skipped.
  • Each step changes every row it should, or none. A failed step is recorded and the steps after it wait; fix the cause and deploy again, or run dv modules data-migrations <CODE> --retry. dv modules data-migrations <CODE> shows each step's status.

seed_data

Sample rows inserted on a workspace's first subscribe, into tables that are still empty.

  • Shape: {"tables": {"<table>": [rows]}}. Each table must be in data_tables.
  • Five to ten rows per main table that show the range of what the table is for. More than 50 gets a warning.
  • Dates must be relative: {"$date": "-30d"}. Units: d, w, mo, y, or now / today.
  • Mark rows as samples so people know what to delete.

storage

Per-workspace file folders with signed links. Each folder has a name, and may set max_file_size_mb, allowed_content_types, signed_url_ttl_seconds and its own permissions (read, write, delete). See the SDK's skills/using-storage/SKILL.md.

ai: the module's agent

json
"ai": {
  "agent": {
    "agent_code": "VISITOR_LOG_AGENT",
    "agent_name": "Visitor Log Agent",
    "persona": "You help reception staff sign visitors in and out...",
    "max_iterations": 20,
    "memory_mode": "automatic"
  },
  "tools": ["list_visits", "sign_out_visitor"],
  "skills": ["daily-summary"]
}
KeyMeaning
agent.agent_code, agent.agent_name, agent.personaWho the agent is and its instructions.
agent.model_preferenceA current model. Leave it out to use the workspace's default model.
agent.max_iterations, agent.temperatureLimits and style.
agent.memory_modeautomatic, manual or disabled.
agent.config.browser_extension_enabledtrue lets the agent use the person's browser.
agent.config.artifacts_enabledOn unless false: the agent can make Excel, PowerPoint, Word and PDF files.
toolsExact function names from ai/tools.py.
skillsFolder names under ai/skills/.

See Agent tools, skills and scripts.

ui: icon, pages and settings

KeyMeaning
iconRequired. An SVG (preferred), PNG or WebP under ui/, 64 KB at most.
nav_itemsThe module's pages under its sidebar row: key, label, page (a file under ui/ that must exist), optional permission, permission_any, section, parent.
nav_labelWhat the sidebar calls the module, if different from its name.
panel_urlThe main page.
tenant_settings_pagetrue for ui/settings.html, or a path: the module's own Configuration tab in Module Settings. Lists the module is driven by (types, categories, statuses) go here, never in nav_items.
public_pagesPages reachable without signing in: key, path, name, description, requires_login, link_only. Each is a security decision.
reports_tabRename the Reports tab ({"label", "section"}) or leave it out with false. Don't add your own Reports page.
chat_suggestionsStarter questions for the module's agent.

Hiding a page in the sidebar is not access control: protect its routes with permissions too.

mobile

Optional. Every module is in the DV Mobile app by default, showing its ui.nav_items.

KeyMeaning
label, iconName and icon in the app.
nav_itemsThe phone's pages, same shape as ui.nav_items.
quick_actionsHome-screen shortcuts: {"label", "nav_item"}.
desktop_onlyui.nav_items keys kept off the phone.
featuresPhone features used: camera, scan, dictate, location, files, signature, video, push.

Unknown keys or pages that don't exist are errors.

services and service_dependencies

services lists what the module offers other modules. The code lives in services.py.

KeyRequiredMeaning
nameYesMust match the name registered in services.py.
descriptionYesWhat it does.
permissionYesThe permission a caller needs. Use none only for a scheduled job's handler.
contractWarning withoutContract major version, "1".
params, resultWarning withoutWhat callers pass and what comes back: {name: type}.
returnsRecommendedA short description of the result.
implementsNoA Data Visions interface it provides, such as "dv.team_members".

service_dependencies lists services the module calls on other modules: module, service, usage and optional are required, contract is expected. "optional": false means the other module is subscribed automatically with yours; true means your module must work without it. A call to another module that isn't declared here is an error. See Platform services for modules.

record_sources and interface_dependencies

record_sources offers records other modules can pick, such as projects or employees: each source has key, label and fields, and may name the interface it implements (dv.project, dv.customer, dv.employee, dv.worker, dv.crew, dv.department). interface_dependencies asks for "any module that provides" one of those interfaces: interface, contract, optional, fields, usage. dv modules interfaces lists the interfaces.

Outside systems

BlockUse it for
uses_integrationsA system your workspace has connected, such as a Microsoft 365 mailbox: integration, service, optional, permission (one of the module's own), why. No credentials in the module.
external_apisAn outside service the module calls itself: id, name, hosts (or host_from_setting), auth, plus contract, credentials, health_check, optional, usage, docs.
egressEvery outside host the code calls, such as "api.example.com" or "erp.example.com:16000", or {"from_setting": "api_url"} when each workspace saves its own address. An undeclared host is a high finding that blocks the deploy.
platform_servicesPaid platform services, such as MAPS, each with why and optional. A Workspace Admin approves them.

events, scheduler and messages

events: publishes (event names beyond the module's own namespace), stream_permission (who may receive them in a browser), stream_payload (ids or full).

scheduler:

json
"scheduler": {
  "entity_types": [{"entity_code": "DAILY_SUMMARY", "name": "Daily summary",
                    "handler": "VISITOR_LOG.send_daily_summary", "default_cron": "0 17 * * *",
                    "timezone": "UTC", "auto_create": true}],
  "agent_triggers": [{"trigger_code": "WELCOME", "name": "Welcome new visitors",
                      "event": "visitor_log.visit_created", "agent_code": "VISITOR_LOG_AGENT",
                      "prompt": "Welcome visitor {payload.id}.", "auto_create": true}]
}

A schedule's handler must be a declared service with no permission. agent_triggers run the module's agent when one of its events fires.

messages: emails the module sends, each with key, name, description, subject, body and placeholders. Each workspace gets its own editable copy of the wording.

tenant_settings

json
"tenant_settings": [
  {"key": "require_host", "type": "boolean", "default": true, "description": "..."}
]

Types: integer, string, boolean. Settings aren't secret: anyone signed in to the workspace can read them. "public": true makes a setting readable without signing in; it isn't allowed for anything named like a credential.

distribution, reporting and marketplace

BlockKeys
distributionvisibility: tenant_only (private) or marketplace (may be submitted). source_access: locked. license: free text. price: shown only, nothing is billed.
reportingOnly when you decided not to publish datasets: {"datasets": false, "reason": "<your reason>"}. Without datasets or this block, you get a recommendation to decide. The Marketplace requires datasets.
marketplacetagline, category, highlights for the Marketplace card.

capabilities and runtime

capabilities.allow_raw_sql: true lets module code run its own SQL on the module's own tables, for queries the normal methods can't express. It is shown to reviewers.

runtime.requirements lists Python packages, pinned exactly ("pypdf==6.20.1"). All of a workspace's modules share one sandbox, so use the same version other modules pin; a conflicting version is refused at install.

Good to know

  • Validate after every change with dv modules validate <folder> or the connector's validate_module. Every finding says how to fix it.
  • The module check validates the manifest again before every deploy. See Publish a module: the module check.
  • Changing the manifest means a new version. Versions can't be changed once deployed.
  • module_code is permanent. Changing it makes a new module.
  • For the step-by-step build, see Build a module with a coding agent, start to finish.

Can't find what you need? Contact support.