Typed input mappings

Typed task input mappings#

Typed input mapping composes independently approved contracts without changing their ownership. A process can copy selected fields from declared variables into the input expected by a service or human task. The compiler validates the mapping; the designer presents schema-based choices.

The documented version 1 extension offers Task input → Copy selected fields. Whole compatible variable remains available when an entire declared variable already matches the task input contract.

Mapping shape#

inputMapping replaces inputVariable. Omit inputVariable or set it to null when field mapping is used. The extension has a version and a fields object that associates each destination property with a source path.

A source path is at most 512 characters. Destination names begin with an ASCII letter or underscore, contain only ASCII letters, digits or underscore, and have at most 64 characters.

Publication checks#

The compiler verifies that every source segment is required by its approved schema. It also verifies that the source variable is assigned on every incoming control-flow path. A field available on only one gateway branch cannot be read unconditionally after the merge.

Every required destination property must have a mapping. Source and destination fields require identical explicit scalar types from the supported set: string, integer, boolean or null.

This is copying, not transformation. Version 1 does not permit inferred mappings, constants, casts, functions, arithmetic, array traversal, scripts or URL construction. Identity and routing context are not data sources for this feature. A process author cannot use mapping to construct a new destination, select a recipient or expand authority.

Runtime validation#

Compatible scalar types do not prove that every value satisfies the destination's full contract. The runtime validates the pinned destination schema before persisting a service operation/outbox command or human task.

For example, a source string may allow a broader length range than the destination. The mapping can be structurally valid, but a particular value still fails the destination constraint. The runtime does not coerce the value or dispatch malformed input.

Bounds, enum restrictions and constants need not be textually identical between the source and destination schemas. Runtime evaluation enforces the destination's constraints. Changed or unapproved schema digests remain invalid regardless of whether a browser can display the fields.

Human task data and recipient authority#

For save-driven recipients, the documented rule permits mapping only from the original input. The human interaction still belongs to the event owner, and verified save proof, event digest, enrolled requester/group and owner permission checks remain required.

Copying fields provides task data. It never supplies recipient eligibility. A value named like a person, group or role does not replace protected identity context or current owner authorization.

Release compatibility#

The mapping document identifies compiler version 1.1.0 with the bounded profile acyclic-v1 and a new content hash. Mapping source participates in compiler and plan fingerprints. The extension does not require a database migration, Matrix Core release or consumer SDK release.

API and Worker must be adopted together, with Web providing the authoring controls. Do not activate mapped definitions while an older Worker can claim their jobs. Publish a new definition version and update its starting rule explicitly; existing definitions and instances remain immutable.

Compatibility retention for older compiler/profile pairs applies to the supported unmapped plans. Once mapped instances exist, rollback must retain mapping-capable execution for those instances. An older Worker cannot safely interpret them. Review definition lifecycle before changing an active mapping.