# 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.

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](article:92da1335-5139-4bf1-8e35-dec5d5556947)).

## 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

| 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

```json
{"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.

```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"}}
]
```

| `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 `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"]
}
```

| 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](article:f1c6d74e-dd1b-4ef1-a375-968d115a6364).

## 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](article:2840da57-7b0d-4140-be73-700db73b5782).

## 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`:

```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

| 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'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](article:cfb41dcb-edee-4f32-979c-d0f041eff1f8).
- **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](article:6e6343d4-3801-4e7d-a21a-9722fb4ee89b).


Source: https://datavisions.ai/docs/developer-tools/module-manifest-module-json-reference
