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

# 6.10 Resource formats and internal interfaces

These formats support imports and internal communication in the current Alpha. Revalidate them when upgrading; they are not a promise of permanent compatibility for a public API.

## 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` | Role definition | Duties, data scope, and execution scope |
| `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.

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

For system integrations, prefer the [supported MCP path](https://docs.teloa.ai/v/0.2.2/markdown/en/develop/mcp.md). If you need a new stable integration interface, define identity, permissions, idempotency, versioning, and error contracts before implementing the adapter.

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