---
title: Resource formats and internal interfaces
description: Check formats, defaults, versions, and errors without relying on unstable APIs.
lastVerified: 2026-10-23
---

# 6.14 Resource formats and internal interfaces

These formats correspond to Community 0.2.8 resource imports and internal communication. Recheck readers when upgrading; business-system invocation is documented separately in the employee API guide.

## Common resource formats

| Format | Purpose | What to check |
| --- | --- | --- |
| `teloa.business-package/v2` | Business package resource list | Resource identities, locked versions, relationships, and scope |
| `teloa.business-package/v3` | Business package with model dependencies | Fixed model declarations and readiness at each entry point |
| `teloa.business-package/v4` | Business package that may include a complete configuration | Only v4 supports `business-configuration`; requires alpha.7 or later |
| `teloa.business-dashboard-resource/v1` | Reusable business dashboard resource | Fixed identity and version, complete configuration v2, closed page and definition references; excludes records, synchronization bindings and default actions |
| `teloa.role/v1` | AI employee role template | Duties, data and execution scopes, and five responsibility groups |
| `teloa.work-template/v1` | Task template | Input requirements, output, and locked skill references |
| `teloa.mcp-connection/v1` | MCP connection definition | serverName and the tool set |
| `teloa.reference-list/v1` | MCP reference list | Sources, byte counts, and SHA-256 versions |
| `teloa.reference/v1` | MCP read result | Content and source for the same version |

A resource package's `scope` defaults to `domain`. Referenced versions must match resource definitions. Do not use JSON field order to determine object equality.

## Share subjects

`teloa.template-share/v2` distinguishes `employee` (exactly one employee), `team` (at least two), `app` (no employees; includes a skill, MCP connection or extension), and `skill` (exactly one skill). Connections can also use `mcp`. Its `files` include the UTF-8 body of `teloa.json`, using business-package/v2, v3 or v4. Identity and fixed version agree across layers; required people/automation/connections/business capabilities are declared. There is no standalone app catalog kind, while the share format has an explicit app subject.

Legacy `teloa.template-share/v1` retains its original single-employee reader. Shared employee definitions omit `runtimeConfig`, a stricter boundary than standalone role imports below. See [sharing](https://docs.teloa.ai/v/0.2.8/markdown/en/guides/sharing.md) for examples and distribution.

## AI employee templates

`teloa.role/v1` is Teloa's current role template import format. [AI Worker Standard 1.0](https://github.com/teloa-ai/ai-worker-standard) describes workers, work contracts and collaboration rules. The standard and this product import format are maintained separately: a standard exchange document is not directly a role template, and unsupported fields cannot be added to this format.

The template uses `name`, `kind`, `duty`, `dataScope` and `executionScope` to describe identity, duties and scope. Creating or editing an employee now requires an explicit `responsibility` object containing these five string arrays:

| Field | Meaning |
| --- | --- |
| `triggers` | Triggers: when to take on work |
| `autonomousActions` | Autonomy: what can be done within existing authorization |
| `confirmationPoints` | Confirmation: which steps require confirmation |
| `escalationRules` | Escalation: how to report or hand over missing information, conflicts or scope limits |
| `deliveryChecks` | Delivery: what the result includes and how completion is checked |

All five fields must be present; each accepts at most 30 entries of up to 1,000 characters. Arrays may be empty, and an empty array grants no additional authority. Current templates have expanded structured responsibilities while retaining the `teloa.role/v1` file format number. For older templates without the entire `responsibility` object, the reader supplies five empty arrays rather than generating duties. New templates should explicitly state the responsibilities relevant to the role.

This example uses English instructions and preserves existing authorization and required confirmations after import:

```json
{
  "format": "teloa.role/v1",
  "name": "Research Assistant",
  "kind": "employee",
  "duty": "Summarize supplied material and distinguish evidence from open questions.",
  "dataScope": "Only supplied material and already authorized references.",
  "executionScope": "Read and draft within existing authorization; retain required confirmations.",
  "responsibility": {
    "triggers": ["When assigned a summary of supplied material."],
    "autonomousActions": ["Read authorized material and draft a source-based summary."],
    "confirmationPoints": ["Ask before expanding the authorized data or execution scope."],
    "escalationRules": ["Report missing or conflicting evidence without inventing conclusions."],
    "deliveryChecks": ["Include sources, findings, open questions and incomplete work."]
  },
  "runtimeConfig": {
    "agentPresetId": "teloa-standard"
  }
}
```

`runtimeConfig` is optional. A template may carry an `agentPresetId`; the receiving host still checks preset availability during preparation. Template `model` and `fallbackModel` selections are ignored rather than inherited. The owner selects and configures models and accounts on the receiving host.

A role template does not carry instance `scopes`, `skills`, `knowledge`, credentials or grants; these fields cannot be inserted into this file. Related resources are bound through the package manifest and the receiving instance. Importing a definition does not connect accounts, start work or expand authority.

## Business dashboard definitions and query limits

Business dashboards add three business definitions. Like record types, views and actions, they go through three steps in order: conversation draft, preview and owner confirmation, and their readers validate fields strictly:

| Format | Purpose | What to check |
| --- | --- | --- |
| `teloa.business-source-mapping/v1` | Data source mapping | The source must be a business data port, a read-only managed MCP tool, or AI employee results; JSONPath subset, 1–3 primary keys, deletion semantics, sync schedule |
| `teloa.business-widget/v1` | Dashboard widget | Seven widget kinds; SQL may reference only record types defined in the scope (table name with `-` replaced by `_`) and their fields; charts are Vega-Lite specs with allow-listed keys |
| `teloa.business-dashboard/v1` | Dashboard | 12-column grid, referenced widgets, refresh schedule (intervals under 60 seconds require `acknowledgeShortInterval: true`; under 10 minutes the page warns about external quota and local resources) |

Widget SQL first passes a syntax-tree allow list (a single SELECT, allow-listed functions and nodes; schema names, system tables, placeholders and multiple statements are rejected). It is then rewritten into a parameterized query over the current versions in the snapshot table for the owner and scope, and runs only after a second validation and a round-trip check. Execution uses the read-only role `teloa_business_reader` over a dedicated connection pool: 5 seconds per query, at most 10,000 rows, 1 MB per row, 8 MB in total, and 5 concurrent queries per scope (per process). In the rewritten query, the snapshot table and the safe conversion functions are qualified with the schema that holds the Teloa tables (the application connection's `current_schema()`, `public` in the personal edition). The allow-list constants are in `packages/backend/src/work/business-sql-whitelist.ts`, and the matching database tests are in `packages/backend/tests/business-sql-guard.test.ts`, `business-sql-rewrite.test.ts` and `business-sql-executor.test.ts`.

The draft tool derives its request identity from the instruction, the definition kind and the definition id: replaying the same definition replaces the same draft, and one instruction can save several different definitions. The returned content body is compared as canonical text (keys sorted), so field order does not matter.

## Unknown fields and corrupt data

Many readers enforce strict field validation. Misspelled fields are not silently ignored. Treat invalid input and corrupt stored data separately: correct the input in the first case; preserve evidence and repair from a trusted backup or source in the second.

## Internal RPC

The client sends internal RPC requests through the Harness. Endpoints, request envelopes, authentication cookies, and response parsing can change between versions. Requests captured in a browser should not be treated as a stable third-party REST interface.

Business systems call employees through the [employee work API, SDK and MCP Server](https://docs.teloa.ai/v/0.2.8/markdown/en/develop/employee-api.md). Employees access external reference services through the [supported MCP path](https://docs.teloa.ai/v/0.2.8/markdown/en/develop/mcp.md). Verify identity, grants and request boundaries separately for each direction.

## Project interfaces

The internal `projects/list`, `projects/get`, `projects/create`, `projects/edit`, and `projects/candidates` endpoints share the project contract. The authenticated session determines ownership. Creation uses a request UUID; edits require `expectedVersion` and reject conflicting updates. The business scope is immutable after creation.

Project links use `task`, `group`, `role`, `plan`, `resource`, or `artifact` plus a record ID. Only available records within the permitted scope can be newly linked. Detail responses derive task progress and deliverables from the linked records. Linking is not an execution authorization and does not change the original records.