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
{
"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 adefault. - 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
| Field | Required | What it is | Example |
|---|---|---|---|
module_code | Yes | Permanent identifier, UPPER_SNAKE_CASE, starts with a letter. Unique on the platform. | "VISITOR_LOG" |
module_name | Yes | Display name. | "Visitor Log" |
version | Yes | Semantic version. Raise it for every change. | "0.2.0" |
distribution | Yes | Private or Marketplace, and source terms. | {"visibility": "tenant_only", "source_access": "locked"} |
ui | Yes (ui.icon) | Icon, sidebar pages, settings page, public pages. | {"icon": "icon.svg"} |
module_description | Expected (warning without) | What the module does. | "Sign visitors in and out..." |
api_base_path | No | Where its routes are mounted. Defaults to /api/v1/<module code in lower case>. | "/api/v1/visitor_log" |
permission_prefix | No | Prefix for permission codes, when it should differ from module_code. | "VISITORS" |
permissions | When it has routes or tools | The permissions the module adds. | see below |
data_tables | No | Tables created in your workspace's database. | see below |
data_migrations | No | One-time steps that reshape existing data. | see below |
seed_data | No (warning without, when there are tables) | Sample rows a new subscriber sees. | see below |
storage | No | File folders for uploads. | see below |
ai | No | The module's agent, its tools and skills. | see below |
capabilities | No | Extra privileges the module opts in to. | {"allow_raw_sql": true} |
runtime | No | Python packages the module needs. | {"requirements": ["numpy==2.4.6"]} |
services | No | Services the module offers other modules. | see below |
service_dependencies | No | Services it calls on other modules. | see below |
record_sources | No | Records other modules can pick and read. | see below |
interface_dependencies | No | "Any module that provides projects" and similar. | see below |
uses_integrations | No | Systems the workspace has connected, such as Microsoft 365. | see below |
external_apis | No | Outside services the module calls. | see below |
egress | No | Every outside host its code calls. | ["api.example.com"] |
platform_services | No | Paid platform services it uses, such as maps. | [{"code": "MAPS", "why": "..."}] |
events | No | Event names it owns and who may receive them. | see below |
scheduler | No | Schedules and event-triggered agent runs. | see below |
messages | No | Emails it sends, as editable templates. | see below |
mobile | No | How it shows in the DV Mobile app. | see below |
tenant_settings | No | Simple settings each workspace can change. | see below |
reporting | No | Your recorded reason for not publishing datasets. | {"datasets": false, "reason": "..."} |
marketplace | No | Marketplace card text. | {"tagline": "...", "category": "Operations"} |
bridge | No | Tools it runs on your own computers through the Bridge. Needs approval by Data Visions. | {"capabilities": ["metrics"], "tools": ["collect_metrics"]} |
desktop_clients | No | Data 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
{"code": "VISITOR_LOG.APPROVE", "label": "Approve visitors",
"description": "Approve visitors waiting at the desk",
"help": "For reception leads.", "default_roles": ["Admin"]}| Key | Required | Meaning |
|---|---|---|
code | Yes | <PREFIX>.ACTION. The prefix is permission_prefix, or module_code. |
description | Yes | What it allows. |
default_roles | Yes | Which roles get it when a workspace subscribes. Use ["Admin"] for nearly everything, or [] for no one until an admin chooses. |
label, help | No | The plain name and the "when to grant it" line a Workspace Admin sees when building a role. |
risk_level | No | For 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.
| Key | Meaning |
|---|---|
name | Table name. |
columns | List of columns. Every table needs a primary key. |
indexes | Optional: [{"columns": ["status", "created_at"]}], with "unique": true for a unique index. |
| Column key | Meaning |
|---|---|
name | Column name. Avoid reserved words such as user, order, type. |
type | UUID, VARCHAR(N), TEXT, INTEGER, BIGINT, SMALLINT, DOUBLE PRECISION, NUMERIC, REAL, FLOAT, BOOLEAN, TIMESTAMPTZ, TIMESTAMP, DATE, TIME, JSONB, JSON, BYTEA, INET, CIDR, MACADDR, INTERVAL. |
primary_key | true for the key column. |
nullable | false for a required column. |
default | A default expression: gen_random_uuid(), NOW(), 'active'. |
unique | true for unique values. |
foreign_key | Another 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.
"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"}}
]op | What it does | Keys |
|---|---|---|
fill | Sets an empty column to a value | table, column, value, optional where |
copy_column | Copies one column into another on the same table, converting the type | table, from, to, optional map, empty_as_null, where |
copy_rows | Copies rows into another table | from_table, to_table, columns, key, optional where |
service | Runs a service your module declares | service |
- Every step needs an
idthat starts with the version, such as0.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 indata_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, ornow/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
"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"]
}| Key | Meaning |
|---|---|
agent.agent_code, agent.agent_name, agent.persona | Who the agent is and its instructions. |
agent.model_preference | A current model. Leave it out to use the workspace's default model. |
agent.max_iterations, agent.temperature | Limits and style. |
agent.memory_mode | automatic, manual or disabled. |
agent.config.browser_extension_enabled | true lets the agent use the person's browser. |
agent.config.artifacts_enabled | On unless false: the agent can make Excel, PowerPoint, Word and PDF files. |
tools | Exact function names from ai/tools.py. |
skills | Folder names under ai/skills/. |
See Agent tools, skills and scripts.
ui: icon, pages and settings
| Key | Meaning |
|---|---|
icon | Required. An SVG (preferred), PNG or WebP under ui/, 64 KB at most. |
nav_items | The module's pages under its sidebar row: key, label, page (a file under ui/ that must exist), optional permission, permission_any, section, parent. |
nav_label | What the sidebar calls the module, if different from its name. |
panel_url | The main page. |
tenant_settings_page | true 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_pages | Pages reachable without signing in: key, path, name, description, requires_login, link_only. Each is a security decision. |
reports_tab | Rename the Reports tab ({"label", "section"}) or leave it out with false. Don't add your own Reports page. |
chat_suggestions | Starter 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.
| Key | Meaning |
|---|---|
label, icon | Name and icon in the app. |
nav_items | The phone's pages, same shape as ui.nav_items. |
quick_actions | Home-screen shortcuts: {"label", "nav_item"}. |
desktop_only | ui.nav_items keys kept off the phone. |
features | Phone 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.
| Key | Required | Meaning |
|---|---|---|
name | Yes | Must match the name registered in services.py. |
description | Yes | What it does. |
permission | Yes | The permission a caller needs. Use none only for a scheduled job's handler. |
contract | Warning without | Contract major version, "1". |
params, result | Warning without | What callers pass and what comes back: {name: type}. |
returns | Recommended | A short description of the result. |
implements | No | A 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
| Block | Use it for |
|---|---|
uses_integrations | A 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_apis | An outside service the module calls itself: id, name, hosts (or host_from_setting), auth, plus contract, credentials, health_check, optional, usage, docs. |
egress | Every 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_services | Paid 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:
"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
"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
| Block | Keys |
|---|---|
distribution | visibility: tenant_only (private) or marketplace (may be submitted). source_access: locked. license: free text. price: shown only, nothing is billed. |
reporting | Only 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. |
marketplace | tagline, 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'svalidate_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_codeis permanent. Changing it makes a new module.- For the step-by-step build, see Build a module with a coding agent, start to finish.