Path Expression Reference

Path expressions are used throughout multi-agent policies (input_mapping, exit_condition, when) to reference data from the execution context. This page defines the formal grammar, error semantics, and usage rules.

Formal Grammar

path_expression = source "." direction "." field_path
source          = "parent" | agent_alias
agent_alias     = [a-zA-Z_][a-zA-Z0-9_]*
direction       = "input" | "output"
field_path      = field_name ( "." field_name | ".[]" )*
field_name      = [a-zA-Z_][a-zA-Z0-9_]*

Production rules:

• source identifies the data origin: parent refers to the enclosing agent, and any other value is resolved as a local_agents[].alias appearing as a prior step in the policy.
• direction selects whether the expression references the agent's input or output.
• field_path navigates into the data structure. The .[] segment iterates over array elements (used in batch policies).

Field Name Constraints

The field_name production is restricted to identifier characters ([a-zA-Z_][a-zA-Z0-9_]*). This eliminates escaping ambiguity entirely by ensuring that the . separator is never part of a field name.

JSON Schema property names containing dots (e.g., "foo.bar"), spaces, hyphens, or other special characters cannot be referenced by path expressions. Agent owners MUST use identifier-safe property names in interface.input and interface.output schemas for any fields that will be referenced in input_mapping or conditions.

This constraint applies to the path expression language only. JSON Schema definitions themselves MAY use any valid property names for fields that are never referenced by path expressions.

Property Name	Referenceable?	Reason
query	Yes	Identifier-safe
data_source	Yes	Underscores allowed
myField2	Yes	Alphanumeric
foo.bar	No	Contains dot -- ambiguous with path separator
my-field	No	Contains hyphen -- not in [a-zA-Z0-9_]
user name	No	Contains space

Examples

Expression	Source	Direction	Field Path	Meaning
parent.input.query	parent	input	query	The parent agent's query input field
researcher.output.findings	researcher	output	findings	The researcher step's findings output field
parent.input.items.[].value	parent	input	items.[].value	Each item's value in the parent's items array
quality_checker.output.score	quality_checker	output	score	The quality_checker step's score output field
parent.input.config.nested.key	parent	input	config.nested.key	Deeply nested field access

Error Semantics

When a path expression does not resolve, the runtime MUST report a validation error before execution begins. Specifically:

• If source references an agent_alias that does not match any local_agents[].alias, the runtime MUST reject the configuration at load time.
• If source references a step that has not yet executed at the point of evaluation (e.g., referencing step B's output from step A's input_mapping when B comes after A in the steps list), the runtime MUST report a dependency ordering error.
• If the field_path does not resolve to a value in the agent's input or output schema, the runtime SHOULD report a warning at load time (when schemas are available) and MUST report an error at execution time when the field is absent.
• If the .[] array iteration syntax is used on a non-array value, the runtime MUST report a type mismatch error.

Usage Contexts

Path expressions appear in the following locations:

Context	Spec Section	Key Format
PolicyStep.input_mapping values	Execution Policies	<source>.<direction>.<field_path>
ConditionGroup.args_match keys (execution policy context)	Condition Matchers	<source>.<direction>.<field_path>
LoopConfig.exit_condition	Execution Policies — Loop	Path expressions in args_match keys
ConditionalRoute.when	Execution Policies — Conditional	Path expressions in args_match keys

Array Iteration Semantics

The .[] operator provides map semantics: each array element is processed independently by the target agent. The runtime produces one invocation per element.

Single [] per expression

In v1.0, a path expression MUST contain at most one .[] segment. Nested iteration (e.g., parent.input.matrix.[].rows.[].value) is not supported. The runtime MUST reject configurations containing path expressions with multiple .[] segments.

Multiple [] across mappings

When multiple fields in one input_mapping use .[], they MUST reference the same array -- that is, the path prefix before .[] MUST be identical. The runtime iterates them in lockstep (zip semantics). If the prefixes differ and the referenced arrays have different lengths, the runtime MUST report a length mismatch error.

# Valid: both fields iterate over the same array (parent.input.items)
input_mapping:
  name:  "parent.input.items.[].name"
  value: "parent.input.items.[].value"

# Invalid: different arrays — runtime MUST reject
input_mapping:
  name:  "parent.input.items.[].name"
  price: "parent.input.prices.[].amount"

Scope restriction

The .[] operator is valid only in BatchConfig.input_mapping. Using .[] in PolicyStep.input_mapping, ConditionalRoute.input_mapping, or ConditionGroup.args_match keys is invalid -- the runtime MUST reject these configurations.

Type Handling

Path expressions resolve to JSON values. The runtime MUST NOT perform implicit type coercion. If a resolved value's JSON type does not match the type expected by the target agent's input schema, the runtime MUST report a type mismatch error.

Null values. If a path expression resolves to an explicit JSON null, the runtime MUST pass null to the target field. If the target field is marked as required by the agent's input schema, the runtime MUST report a validation error.

Absent values. If a path expression resolves successfully (the source agent produced output) but the specific field is absent from the output object, the behavior depends on the target field's schema: if the target field has a default, the runtime SHOULD apply the default; if the target field is required and has no default, the runtime MUST report a missing value error.