# Diagnostics and XML reference

The XML document and its resulting definition are each limited to 2 MiB. Unknown
elements or attributes, duplicate logical ids, malformed JSON Schema, undeclared
references, unsafe XML and excessive input/output are hard errors. XML external
entities, processing instructions and namespace escapes are forbidden.

Diagnostics identify the affected fields and locations in your original XML.
Offsets are UTF-8 bytes; line and column numbers are one-based, with UTF-16 editor
columns. End positions are exclusive. Nested Workflow, EdgeApp and script errors
map into the outer document, including escaped inline text and split CDATA.

The source editor uses this catalog for XML completion, hover descriptions and
syntax help. Validation markers use the original XML ranges. Select a diagnostic
to move the cursor to its source location. Editing clears diagnostics from the
previous document; validate the new buffer to refresh them. Published definitions
remain read only.

Use the vocabulary below to look up supported elements, attributes and limits.
For embedded Edge Apps and Workflows, also consult their authoring manuals.

## Integration XML v1 vocabulary

The XML describes a reusable definition. Its instances supply configuration, secrets and resource bindings.

### `<integration>` in document

XML v1 definition of Integration behavior and required configuration.

Field path: ``

- `id` → `integrationId` (required): ^[a-z0-9][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*)+$.

- `sdk-version` → `sdkVersion` (required): ^[0-9]+\.[0-9]+$.

- `timeout-ms` → `timeoutMs`: Integer 1...60000; runtime default 5000.

- `version` → `version` (required): ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$.

Children: `<actor>`, `<api-clients>`, `<configuration-schema>`, `<custom-apps>`, `<data-container-schemas>`, `<description>`, `<edge-apps>`, `<policy>`, `<protobuf>`, `<resources>`, `<workflows>`

### `<api-clients>` in integration

Package-owned API clients; credentials are runtime inputs.

Field path: `/apiClients`

Children: `<api-client>`

### `<api-client>` in api-clients

A pinned API contract and original Swagger/OpenAPI source.

Field path: `/apiClients/{index}`

- `name` → `name` (required): ^[a-z_][a-z0-9_]*$.

Children: `<definition>`, `<schema>`

### `<schema>` in api-client

Original Swagger 2 or OpenAPI 3.0/3.1 JSON source as text.

Field path: `/apiClients/{index}/schema`

Text or CDATA.

### `<definition>` in api-client

DataXML API definition as escaped text or CDATA; no credential values.

Field path: `/apiClients/{index}/definition`

Text or CDATA.

### `<protobuf>` in integration

Up to 256 named inline declarations. Imports may reference other inline proto declarations by name.proto only.

Field path: `/protobuf`

Children: `<declaration>`

### `<declaration>` in protobuf

Inline protobuf source (256 KiB) or a whitespace-tolerant base64 FileDescriptorSet (256 KiB decoded). External imports are unavailable.

Field path: `/protobuf/{index}`

- `name` → `name` (required): Unique logical identifier.

- `type` → `type` (required): proto or b64.

Text or CDATA.

### `<custom-apps>` in integration

Up to 256 inline v3 definition assets; no installations or supporting files.

Field path: `/customApps`

Children: `<custom-app>`

### `<custom-app>` in custom-apps

One complete App.vue component, without separate supporting files.

Field path: `/customApps/{index}`

- `handle` → `handle` (required): Unique lowercase identifier.

- `icon` → `icon`: Optional icon.

- `kind` → `kind` (required): PAGE, DASHBOARD, KIOSK, JOB_VIEW.

- `name` → `name` (required): Logical identifier.

Children: `<server-api>`, `<source>`

### `<source>` in custom-app

Complete exact decoded App.vue; nonempty, at most 512 KiB. No files container.

Field path: `/customApps/{index}/source`

Text or CDATA.

### `<server-api>` in custom-app

Optional CustomApp Lua exports API; at most 256 KiB.

Field path: `/customApps/{index}/serverAPI`

Text or CDATA.

### `<edge-apps>` in integration

Complete child edge-app definitions using the Edge Apps XML vocabulary; unique handles, at most 256.

Field path: `/edgeApps`

Children: `<edge-app>`

### `<description>` in integration, resource requirement, Action, or container schema

Definition description; exact decoded text.

Field path: `/description, /resources/{index}/description, /actor/actions/{index}/description, or /dataContainerSchemas/{index}/description`

Text or CDATA.

### `<configuration-schema>` in integration

Inline JSON Schema draft 2020-12 object; 256 KiB and 50 levels; local references within one schema resource only (no nested $id). Advertises installation configuration, never supplies it.

Field path: `/configurationSchema`

Prefer a schema root in urn:cococo:json-schema:1. Legacy JSON text or CDATA remains accepted. See the XML schemas manual.

### `<resources>` in integration

Up to 256 abstract binding requirements.

Field path: `/resources`

Children: `<resource>`

### `<resource>` in resources

Logical requirement; installations supply concrete entities.

Field path: `/resources/{index}`

- `id` → `id` (required): ^[a-z_][a-z0-9_]*$.

- `optional` → `optional`: true or false.

- `type` → `type` (required): ^((template|script|apiclient)(/[A-Z0-9_]+)?|[a-z]+/[a-z]+)$.

Children: `<description>`

### `<policy>` in integration

Typed IAM document, 1...256 statements.

Field path: `/policy`

- `version` → `version`: 2026-01-01.

Children: `<allow>`, `<deny>`

### `<allow>` in policy

ALLOW statement, 1...256 actions and resources.

Field path: `/policy/statements/{index}`

Children: `<action>`, `<resource>`

### `<deny>` in policy

DENY statement, 1...256 actions and resources.

Field path: `/policy/statements/{index}`

Children: `<action>`, `<resource>`

### `<action>` in allow or deny

IAM action pattern, e.g. job:read or *; accepts the dotted contract spelling too.

Field path: `/policy/statements/{index}/actions/{index}`

Text or CDATA.

### `<resource>` in allow or deny

* or a declared logical resource identifier; concrete installation IDs are forbidden.

Field path: `/policy/statements/{index}/resources/{index}`

Text or CDATA.

### `<data-container-schemas>` in integration

Up to 256 named integration-owned container contracts.

Field path: `/dataContainerSchemas`

Children: `<schema>`

### `<schema>` in data-container-schemas

Schema for installation-owned data. No container values are defined here. Omitted taggable types prohibit attachments.

Field path: `/dataContainerSchemas/{index}`

- `max-per-instance` → `maxPerInstance`: Integer 1...1000000; omitted means no count limit.

- `name` → `name` (required): Logical identifier.

Children: `<description>`, `<json-schema>`, `<taggable-type>`

### `<json-schema>` in schema

Required JSON Schema draft 2020-12 object, maximum 256 KiB; local references only.

Field path: `/dataContainerSchemas/{index}/schema`

Prefer a schema root in urn:cococo:json-schema:1. Legacy JSON text or CDATA remains accepted. See the XML schemas manual.

### `<taggable-type>` in schema

Permitted attachment entity type: job or customer; unique within the container schema.

Field path: `/dataContainerSchemas/{index}/taggableTypes/{index}`

Text or CDATA.

### `<workflows>` in integration

Up to 256 named embedded Workflow XML documents.

Field path: `/workflows`

Children: `<workflow>`

### `<workflow>` in workflows

Complete Workflow XML as inline text or CDATA, maximum 256 KiB. Use the Workflow XML vocabulary; YAML is unavailable.

Field path: `/workflows/{index}`

- `name` → `name` (required): Logical identifier.

Text or CDATA.

### `<actor>` in integration

Script actor behaviour; no entry script or exports convention.

Field path: `/actor`

Children: `<actions>`, `<init>`, `<libraries>`, `<shutdown>`, `<subscriptions>`, `<timers>`, `<upgrade>`

### `<init>` in actor

Optional Lua startup chunk; varargs (config).

Field path: `/actor/initSource`

Text or CDATA.

### `<shutdown>` in actor

Optional Lua shutdown chunk; varargs (config).

Field path: `/actor/shutdownSource`

Text or CDATA.

### `<upgrade>` in actor

Optional Lua explicit upgrade chunk; varargs (oldVersion, newVersion, oldConfig).

Field path: `/actor/upgradeSource`

Text or CDATA.

### `<libraries>` in actor

Up to 256 named inline Lua modules.

Field path: `/actor/libraries`

Children: `<library>`

### `<library>` in libraries

Module loaded by ctx.script.load(name).

Field path: `/actor/libraries/{index}`

- `name` → `name` (required): Logical identifier.

Text or CDATA.

### `<subscriptions>` in actor

Up to 256 topic subscriptions. Filters are deferred and rejected.

Field path: `/actor/subscriptions`

Children: `<subscription>`

### `<subscription>` in subscriptions

Inline Lua event chunk; varargs (event, config).

Field path: `/actor/subscriptions/{index}`

- `topic` → `topic` (required): resource.verb event topic.

Text or CDATA.

### `<timers>` in actor

Up to 256 named timers.

Field path: `/actor/timers`

Children: `<timer>`

### `<timer>` in timers

Inline Lua timer chunk; varargs (timerName, config); exactly one of every/cron. Cron uses UTC.

Field path: `/actor/timers/{index}`

- `cron` → `schedule/cron`: Standard five-field cron schedule.

- `every` → `schedule/every`: Integer seconds or s/m/h duration, 1...86400 seconds.

- `jitter` → `jitter`: s/m/h duration, 0...3600 seconds; at most the interval for every timers.

- `name` → `name` (required): Logical identifier.

Text or CDATA.

### `<actions>` in actor

Up to 256 callable Actions, shared by direct calls and Workflow nodes.

Field path: `/actor/actions`

Children: `<action>`

### `<action>` in actions

Named Action; inline source receives (input, actionConfig); instance config is available through ctx.config.get().

Field path: `/actor/actions/{index}`

- `icon` → `icon`: Optional icon name.

- `label` → `label` (required): Display label.

- `name` → `name` (required): Logical identifier.

Children: `<config-schema>`, `<description>`, `<input-schema>`, `<output-schema>`, `<source>`

### `<source>` in action

Required Lua implementation, maximum 256 KiB.

Field path: `/actor/actions/{index}/source`

Text or CDATA.

### `<input-schema>` in action

Optional inline JSON Schema for callable input.

Field path: `/actor/actions/{index}/inputSchema`

Prefer a schema root in urn:cococo:json-schema:1. Legacy JSON text or CDATA remains accepted. See the XML schemas manual.

### `<config-schema>` in action

Optional inline JSON Schema for Action settings.

Field path: `/actor/actions/{index}/configSchema`

Prefer a schema root in urn:cococo:json-schema:1. Legacy JSON text or CDATA remains accepted. See the XML schemas manual.

### `<output-schema>` in action

Optional inline JSON Schema for the return value; inferred when absent.

Field path: `/actor/actions/{index}/outputSchema`

Prefer a schema root in urn:cococo:json-schema:1. Legacy JSON text or CDATA remains accepted. See the XML schemas manual.