Connector Manifests

A connector manifest is a document using the serialization rules that publishes one connector’s actions and triggers. It describes the contract visible to Workfiles and executors; it does not identify an implementation, endpoint, credential, or configured account.

Manifest structural maps follow the closed-map rule under Duplicate and Unknown Keys unless a subsection permits an extension key. Unknown manifest keys are invalid under that same rule.

Names declared by a manifest MUST match the Workfile name syntax. Connector namespaces remain subject to the lowercase catalog-namespace syntax.

Manifest Structure

A manifest has the following form. It MUST declare at least one action or trigger.

Key	Required	Meaning
manifest	Yes	Connector-manifest format version.
connector	Yes	Connector namespace.
version	Yes	Connector artifact version.
auth	Yes	Authentication contract.
connection	No	Deployment connection fields.
self_hosted	No	Permits an unpatterned host connection field when true.
actions	At least one	Action declarations.
schemas	No	Named schemas.
triggers	At least one	Trigger declarations.

The table expresses the nonempty-manifest requirement through the actions and triggers rows. self_hosted, when present, MUST be a boolean.

Unknown top-level keys are governed by Duplicate and Unknown Keys and Extensions and Forward Compatibility.

The overview provides a complete connector manifest.

Manifest Identity and Version

manifest is the required positive integer version of the connector-manifest format. An implementation MUST reject a format version it does not support.

The required connector and version fields are identified in the manifest table above. version is a SemVer 2.0.0 version; comparison follows References and Versions, while build metadata is part of artifact identity but not precedence.

Within one major connector version, a later version MUST NOT remove an action, trigger, or field; change an existing field’s type or meaning; change an error to a less recoverable classification; or weaken an operational promise.

For inputs, a later version MUST NOT add a required field or make an optional field required, and MUST NOT narrow an accepted input. For action outputs and trigger payloads, a later version MUST NOT widen a promised output. It MAY add required output fields or make optional output fields required, provided the result still satisfies the earlier output contract.

A later version MAY add actions, triggers, error codes, or optional fields subject to these compatibility rules.

An incompatible change requires a new major version.

Connector Namespace

connector is the namespace prefix used by every connector.action and connector.trigger operation published by the manifest. It MUST be unique within the catalog namespace that publishes it.

Namespace ownership, reserved names, version selection, and resolution are defined by Catalog and Packaging; the manifest does not redirect or alias its namespace.

Authentication

auth MUST be present and contains type, an authentication scheme, and optional scopes, a list of distinct opaque strings.

The scheme MUST be registered below or match vendor-auth-scheme. An implementation determining connection support MUST reject an unsupported or unknown scheme with deployment.connection rather than infer authentication behavior.

The Authentication Scheme Registry defines the minimum credential material supplied by a deployment. Its representation, acquisition, refresh, storage, and application to a protocol request are outside this specification and are never workflow values.

Scheme	Required connection fields	Deployment credential material	scopes
none	None imposed by the scheme.	None; no credential or authentication flow.	Prohibited.
api_key	None imposed by the scheme.	One opaque API-key credential.	Permitted.
bearer	None imposed by the scheme.	One opaque bearer-token credential.	Permitted.
basic	None imposed by the scheme.	A username and password.	Permitted.
oauth2	None imposed by the scheme.	Authorization material sufficient for the connector implementation to obtain and refresh an OAuth 2 access token.	Permitted.

A vendor-authentication scheme defines its credential material and whether scopes is permitted as part of its vendor contract. Every action and trigger requires the union of auth.scopes and its own declared scopes.

Before activating a trigger or dispatching an action, the implementation performing that function, when it can determine granted scopes, MUST verify the union and report an unsupported deployment if any is absent. Credentials and granted scopes are not workflow values.

Connection Fields

connection maps names to base field declarations extended with source, prompt, and in. The map is closed: a connection value MUST NOT contain an undeclared field.

source is user or auth and defaults to user; it states whether an operator supplies the value or the authentication flow returns it. prompt is optional presentation text.

in is host or path and declares that the value contributes to the contacted address. A field with in: host MUST declare a pattern unless the manifest declares top-level self_hosted: true.

For such a self-hosted manifest, an unpatterned host field is permitted and the implementation connecting to that host MUST apply its host-access policy. Connection fields are validated when a connection is created or refreshed.

Connection fields are deployment configuration, are never placed in workflow scope, and MUST NOT be accepted as ordinary action arguments.

Named Schemas

schemas maps names to object types under Object Types and the Workfile Schema Dialect. A manifest field refers to one as $ref: "#/schemas/<name>".

References MUST resolve within the same manifest. A schema can instead consist solely of defined_by: connection, as defined under Extension Points.

Manifest action, trigger, connection, and schema fields use the Field Declarations defined by Workfile Core. A manifest field declaration’s $ref MUST resolve to a schema in that manifest.

An absent optional manifest field with no default is omitted from an argument or object; unlike an absent optional workflow input or state acceptance, it is not supplied as null. Connection fields admit the additional keys defined above.

Extension Points

A named schema whose sole entry is defined_by: connection is an extension point with base type map[string, json]. No other value of defined_by is defined.

A reference to it identifies an extension region whose fields can be refined by the producing connection’s schema overlay. Without an overlay, indexing an extension region has ordinary dynamic map semantics, while member access into it is invalid.

Dynamic maps and extension regions can preserve arbitrary string keys from an upstream system; a key that does not match the Workfile name syntax is reached with a string index. A manifest intended for one fixed deployment SHOULD declare known fields as an ordinary schema rather than as an extension point.

Actions

actions maps action names to declarations. An action declaration admits scopes, input, output, errors, retry, idempotency, idempotency_input, effects, dry_run, deterministic, validated_output, and advisory rate_limit and sample keys.

Action Inputs and Outputs

input is a closed map of field declarations. Before dispatch, the executor MUST apply defaults, reject absent required fields and unknown fields, and validate the complete argument map.

output is either a map of field declarations or one $ref; its absence declares no result value. A successful action with no output MUST NOT create a readable step binding.

An output map describes one object value with additionalProperties: true. An undeclared runtime member is retained with static type json and is reachable by string indexing, but it does not create a statically valid member-access path.

Required output fields MUST be present; optional absent fields are omitted. Output declarations define statically valid expression paths even when runtime validation is not promised.

Errors and Classification

errors maps connector error codes to maps containing required class and optional diagnostic message. class is retryable, fatal, or unknown, as defined under Error Classification.

A key matches connector-code, connector-code-prefix-pattern, or http-status-pattern in the Syntax Reference. A key matching a pattern production is a pattern rather than an exact connector code.

Precedence is defined under Code-Pattern Matching. An uncovered connector code is unknown.

Connector Execution Contract defines how a classification and the action’s declared effects determine the attempt result.

A connector manifest MUST NOT declare an exact code or dotted-prefix pattern beginning with a namespace segment allocated by the Error Code Registry, followed by .. Restrictions on executor-produced connector codes are defined under Reserved Connector Code Registry. message is presentation text and is not available to expressions.

Retry Policy

retry declares an action’s default retry policy using the fields defined under retry. That section defines the fallback when the manifest omits a policy; Effective Retry Policy defines the schedule.

A declared policy MUST contain attempts and backoff. The conditional requirements for initial and max are defined under retry.

Retry never changes an error’s classification.

Eligibility is governed by the retryable-result rule under Effective Retry Policy.

Idempotency

Every action MUST declare idempotency as inherent, keyed, or none.

• inherent promises that reissuing the action with identical arguments has the externally observable effect of one issue.
• keyed promises the same for issues carrying one equal caller-supplied key. It requires idempotency_input, which MUST name a required string input reserved to receive the step’s idempotency_key value.
• none makes no reissue promise and MUST NOT declare idempotency_input.

An action with effects: read MUST declare idempotency: inherent.

Note. The read-effects promise under Effects and Dry Runs makes reissue inherently idempotent. Intervening external changes can still produce a different read result; idempotency does not imply determinism.

The Workfile-side key contract is defined under idempotency_key; retry and reissue follow Effective Retry Policy and Core Ambiguity Disposition.

Effects and Dry Runs

effects MUST be present and MUST be read or write. read promises that the action observes without changing an external system; write makes no such promise.

An action declaring dry_run: delegate promises not to commit external change when invoked in a dry run. dry_run has no other value and MUST NOT appear on a read action.

Run-level dispatch, suppression, output evaluation, and timer and event behavior are defined under Dry Runs.

Operational Promises

deterministic and validated_output MUST be present and MUST be booleans.

deterministic: true promises the same result for equal evaluated arguments, resolved connector and action identity, connector version, selected connection identity and overlay digest, and run.dry_run. The result MUST be invariant under every other invocation-context value, including logical step identity, attempt number, timeout, and fixed idempotency key. A connector that needs another result-affecting value MUST declare it as an action input.

Only a deterministic: true result MAY be reused, and only for an invocation in which all of the result-affecting values listed above are equal.

Recording a result for continuation is not caching. validated_output: true promises that every successful result satisfies output.

The executor MUST completely validate it before binding. validated_output: false does not remove the declared static shape, but the executor is not required to reject a mismatching connector result except that boundary decoding of every encountered type-producing schema node or equivalent type expression is always required.

A carrier that cannot be decoded is invalid_output, including when validated_output is false. An action’s ordinary output supports enum closure only when its resolved declaration has validated_output: true, as defined under Closed Enum Domains.

rate_limit and sample are advisory metadata. They MUST NOT alter logical results or weaken any requirement above.

Events and Triggers

triggers maps trigger names to declarations. A trigger admits kind, scopes, binds, input, output, correlate_on, delivery_id, and advisory sample.

Trigger Kinds

Every trigger MUST declare kind as schedule, external, or poll. The kind structurally requires the corresponding initiation capability.

A polling trigger’s cursor is deployment state owned by the trigger binding; it is not a workflow value. A Workfile MUST NOT modify the cursor. Transport details and polling cadence are configuration unless exposed as declared trigger inputs.

Payload Bindings

binds MUST be present and names the trigger’s default payload binding. input declares a closed map of configuration fields, and configuration MUST NOT contain an undeclared field.

output is a field-declaration map or one $ref and declares the event payload type. A field-declaration map has additionalProperties: true: an undeclared runtime member is retained with static type json and is reachable by string indexing, but it does not create a statically valid member-access path. A $ref instead uses the referenced schema’s additionalProperties rule.

Before a run begins, configuration and payload MUST be validated as defined under Triggers. A trigger with no output delivers an empty object.

Correlation

correlate_on is an optional nonempty list of distinct field names. Each name MUST identify a required top-level field of the trigger output with a non-null scalar type.

A wait or state subscription can match only these fields and MUST supply at least one of them. Their values select runs; they do not establish delivery uniqueness.

Delivery Identity

An external or poll trigger MUST declare delivery_id naming a required top-level string field of its output. A schedule trigger MUST NOT declare it.

For one activated workflow and trigger binding, equal delivery identities denote the same upstream event. The initiation implementation MUST suppress redelivery after the event has been accepted, including while its run is queued, active, suspended, or terminal, for the retention period required by the active capability.

Delivery identity is transport metadata represented within the payload so it can be recorded and audited. It does not become a separate root binding, does not order events, and is independent of correlation fields and run.id.

Connections and Schema Overlays

Deployment Connections

A deployment connection associates one connector version with credentials, granted scopes, connection-field values, and optionally one schema overlay. Its name and storage format are deployment concerns.

A connection is complete only when every required connection field has a valid value and its authentication is usable.

Selection and support classification are defined under Connection Selection. Connection contents are governed by Credentials and Sensitive Values.

Tenant-Defined Schemas

A schema overlay is a document using the serialization rules with exactly the following top-level keys, all required:

Key	Meaning
overlay	Positive integer overlay-format version.
connector	Target connector namespace.
connection	Target deployment connection identity.
schemas	Extension-point refinements.

Unknown overlay keys are governed by Duplicate and Unknown Keys and Extensions and Forward Compatibility. schemas maps extension-point names to maps of field declarations.

At most one overlay applies to a connection. It MUST target that connection’s connector and MUST refine only schemas declared defined_by: connection.

An overlay MUST NOT introduce an extension point or change a manifest-declared ordinary schema. Overlay field declarations can use sensitive; all other field rules apply.

Overlay Validation

An overlay MUST be resolved and validated with its manifest and connection before a dependent Workfile is activated. Its digest is fixed for a run.

Member access into an extension region is valid only for overlay-declared fields. Input extension regions are closed and reject undeclared fields; validated output regions are open, validating declared fields while retaining undeclared fields as json.

Static checks use the overlay of the connection that produces or consumes the value. If that connection cannot be determined unambiguously during validation, member access into the region is invalid.

Overlay format, target, unknown-schema, invalid-field, and missing-field diagnostics MUST distinguish those conditions; diagnostic wording is implementation-defined.

Connector Execution Contract

One action attempt returns exactly one of: success with its declared result, classified failure with a connector code, or ambiguity with a connector code. Transport adapters and connector implementations MUST normalize their native result into this contract.

Cancellation is an executor event, not a connector classification. A retryable or fatal connector code produces a classified failure.

For an effects: write action, an explicitly unknown or uncovered code and loss of acknowledgement after dispatch produce ambiguity unless the executor establishes a definite failure. For an effects: read action, those conditions produce a definite retryable failure because the action cannot have changed an external system.

The Reserved Connector Code Registry allocates executor-produced codes and defines their restrictions on manifest declarations; this section defines their attempt results.

Decoded and native connector results and error details use the boundary materialization rule under Map Order.

The invocation context includes the resolved connector and connection identities, logical step identity, attempt number, fixed idempotency key when applicable, timeout, and run.dry_run. These values are not action inputs unless this section expressly maps one to a declared input.

Action Timeouts

The bound is established by the action timeout modifier or an enclosing deadline.

If the bound expires before dispatch, the attempt is a definite retryable failure with reserved connector code timeout. If it expires after dispatch for an action whose manifest declares effects: read, the attempt has the same definite failure and code: the manifest promises that the action cannot have changed an external system, so loss of its result does not make an external effect ambiguous.

Note: A read timeout after dispatch can leave the returned value unknown, but it cannot leave an external effect in doubt. It is therefore a definite failure rather than an ambiguous result.

If the bound expires after dispatch for an action whose manifest declares effects: write, the attempt is ambiguous with reserved connector code timeout unless the executor can establish a definite failure. A definite retryable timeout follows Effective Retry Policy.

An ambiguous timeout follows Core Ambiguity Disposition or Ambiguous Outcomes and on_unknown. Manifest restrictions are defined under Reserved Connector Code Registry.

When an applicable history profile requires action-attempt history, the executor MUST record the effective timeout, whether dispatch occurred, and the resulting timeout classification. A subsequent response to the timed-out attempt is a late result.

Successful Results

A success asserts that the requested operation completed. Its result MUST undergo boundary decoding, and MUST have the manifest-declared shape when validated_output is true.

Failure to decode a type-producing carrier, or a complete-validation violation when validation is promised, is a definite fatal failure with reserved connector code invalid_output; it creates no binding, MUST NOT be retried, and follows ordinary definite-failure policy, including catch, rather than on_unknown. On valid success, the step succeeds and binds the materialized result when one is declared.

Classified Failures

A classified failure asserts that the attempt did not produce the requested success and that its external effect is not ambiguous. It carries a stable connector code and optional json details.

Retryable failures follow Effective Retry Policy, while fatal failures do not.

Ambiguous Results

An ambiguous result means the executor cannot establish whether the operation took effect. It carries a stable connector code and optional json details.

An ambiguous attempt follows Core Ambiguity Disposition unless an explicit Ambiguous Outcomes and on_unknown policy applies. Terminating the run for unresolved ambiguity does not convert the attempt into a definite action failure: its external effect remains unknown and the action creates no binding.

Cancellation of a dispatched action is governed by Core Cancellation; it is an executor event rather than a connector result and can leave the external effect unknown.