Skip to content

Commit fafecf7

Browse files
committed
fix(workflow): validate declared input and output schemas at publish and run boundaries (issue agentic-ai-java#274)
- WorkflowDefinitionValidator: parse non-blank inputSchema/outputSchema with the networknt draft 2020-12 registry; blank rejection and no-schema behavior unchanged - WorkflowAgent: compile declared schemas at construction; validate request inputs before the first step (no tool or agent side effects); validate the output snapshot on the shared completion path before delivering COMPLETED; failures carry AgentResult.OutputValidationIssue and terminate the stream with WorkflowValidationException - ExecutionResult.continueWith: keep the suspension-point snapshot so a suspended outcome can be built (pre-existing NPE, untested path) - boundaries: resumes do not re-validate inputs; subflow input schemas are a publish-time contract, not an extra gate inside the parent run - tests: WorkflowSchemaContractTest, 10 cases (red 5F+2E before, green after)
1 parent 9e5c95c commit fafecf7

5 files changed

Lines changed: 473 additions & 40 deletions

File tree

‎argi-orchestration/argi-workflow-core/pom.xml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,10 @@
4343
<groupId>com.fasterxml.jackson.core</groupId>
4444
<artifactId>jackson-databind</artifactId>
4545
</dependency>
46+
<dependency>
47+
<groupId>com.networknt</groupId>
48+
<artifactId>json-schema-validator</artifactId>
49+
</dependency>
4650
<dependency>
4751
<groupId>org.junit.jupiter</groupId>
4852
<artifactId>junit-jupiter</artifactId>

‎argi-orchestration/argi-workflow-core/src/main/java/io/github/agentic/ai/workflow/WorkflowAgent.java‎

Lines changed: 99 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -16,11 +16,16 @@
1616
package io.github.agentic.ai.workflow;
1717

1818
import com.fasterxml.jackson.databind.ObjectMapper;
19+
import com.networknt.schema.Error;
20+
import com.networknt.schema.Schema;
21+
import com.networknt.schema.SchemaRegistry;
22+
import com.networknt.schema.SpecificationVersion;
1923
import io.github.agentic.ai.agent.Agent;
2024
import io.github.agentic.ai.agent.AgentEvent;
2125
import io.github.agentic.ai.agent.AgentExecutionContext;
2226
import io.github.agentic.ai.agent.AgentOutcome;
2327
import io.github.agentic.ai.agent.AgentRequest;
28+
import io.github.agentic.ai.agent.AgentResult;
2429
import io.github.agentic.ai.api.chat.ChatMessage;
2530
import io.github.agentic.ai.api.chat.ContentPart;
2631
import io.github.agentic.ai.api.chat.ToolCall;
@@ -44,13 +49,31 @@
4449
import java.util.concurrent.Flow;
4550
import java.util.concurrent.Semaphore;
4651
import java.util.function.Function;
52+
import tools.jackson.databind.JsonNode;
53+
import tools.jackson.databind.json.JsonMapper;
4754

4855
/**
4956
* Independent workflow executor. It interprets the closed workflow DSL directly and
5057
* never creates or references StateGraph, CompiledGraph or Loop runtime classes.
58+
*
59+
* <p>
60+
* When the definition declares an input schema, the request inputs are validated
61+
* against it before the first step runs — before any tool or agent side effect. When
62+
* it declares an output schema, the completed output snapshot is validated before the
63+
* COMPLETED outcome is delivered; a violating output terminates the stream with a
64+
* {@link WorkflowValidationException} instead. Inputs are validated on the fresh run
65+
* only: a resume request continues from the state owned by its continuation and often
66+
* carries no inputs, so re-validating them there would make suspended workflows
67+
* impossible to complete. Subflows share the parent run's inputs, so a nested
68+
* definition's input schema is a publish-time contract for its own callers and is not
69+
* applied again at the subflow entry.
5170
*/
5271
public final class WorkflowAgent implements Agent {
5372

73+
private static final JsonMapper JSON = JsonMapper.builder().build();
74+
75+
private static final SchemaRegistry SCHEMAS = SchemaRegistry.withDefaultDialect(SpecificationVersion.DRAFT_2020_12);
76+
5477
private final WorkflowDefinition definition;
5578

5679
private final Function<String, Agent> agentResolver;
@@ -65,6 +88,10 @@ public final class WorkflowAgent implements Agent {
6588

6689
private final Map<String, StoredContinuation> continuations = new ConcurrentHashMap<>();
6790

91+
private final Schema inputSchema;
92+
93+
private final Schema outputSchema;
94+
6895
private WorkflowAgent(Builder builder) {
6996
this.definition = Objects.requireNonNull(builder.definition, "definition must not be null");
7097
this.definition.validate();
@@ -73,6 +100,8 @@ private WorkflowAgent(Builder builder) {
73100
this.registry = Objects.requireNonNull(builder.registry, "registry must not be null");
74101
this.mapper = Objects.requireNonNull(builder.mapper, "mapper must not be null");
75102
this.subflowMaxDepth = builder.subflowMaxDepth;
103+
this.inputSchema = compileSchema(definition.inputSchema());
104+
this.outputSchema = compileSchema(definition.outputSchema());
76105
}
77106

78107
public static Builder builder(WorkflowDefinition definition) {
@@ -90,6 +119,34 @@ public WorkflowDefinition definition() {
90119
return definition;
91120
}
92121

122+
private static Schema compileSchema(String schemaText) {
123+
return schemaText == null ? null : SCHEMAS.getSchema(schemaText);
124+
}
125+
126+
private static void validate(Map<String, Object> value, Schema schema, String boundary) {
127+
if (schema == null) {
128+
return;
129+
}
130+
JsonNode node;
131+
try {
132+
node = JSON.valueToTree(value);
133+
}
134+
catch (RuntimeException exception) {
135+
throw new WorkflowValidationException("Workflow " + boundary + " is not representable as JSON",
136+
List.of(new AgentResult.OutputValidationIssue(AgentResult.ERROR_CODE_SCHEMA_MALFORMED, "$",
137+
"Workflow " + boundary + " is not representable as JSON: " + exception.getMessage())));
138+
}
139+
List<AgentResult.OutputValidationIssue> issues = new ArrayList<>();
140+
for (Error error : schema.validate(node)) {
141+
issues.add(new AgentResult.OutputValidationIssue(AgentResult.ERROR_CODE_SCHEMA_VIOLATION,
142+
error.getInstanceLocation().toString(), error.getMessage()));
143+
}
144+
if (!issues.isEmpty()) {
145+
throw new WorkflowValidationException(
146+
"Workflow " + boundary + " does not match the declared " + boundary + "Schema", issues);
147+
}
148+
}
149+
93150
public static final class Builder {
94151

95152
private final WorkflowDefinition definition;
@@ -204,44 +261,51 @@ public synchronized void cancel() {
204261
}
205262
}
206263

207-
private void runSafely() {
208-
try {
209-
ExecutionResult result = run();
210-
if (!cancelled) {
211-
if (result.suspension != null) {
212-
String token = register(result.continuation);
213-
AgentOutcome outcome = new AgentOutcome(AgentOutcome.Status.SUSPENDED, result.data.messages,
214-
result.data.state, result.data.usage(),
215-
new AgentOutcome.Suspension(token, result.suspension.prompts()));
216-
emit(new AgentEvent.Finished(outcome));
217-
}
218-
else {
219-
AgentOutcome outcome = AgentOutcome.completed(result.data.messages, result.data.state,
220-
result.data.usage());
221-
emit(new AgentEvent.Finished(outcome));
222-
}
223-
subscriber.onComplete();
264+
private void runSafely() {
265+
try {
266+
ExecutionResult result = run();
267+
if (!cancelled) {
268+
if (result.suspension != null) {
269+
String token = register(result.continuation);
270+
AgentOutcome outcome = new AgentOutcome(AgentOutcome.Status.SUSPENDED, result.data.messages,
271+
result.data.state, result.data.usage(),
272+
new AgentOutcome.Suspension(token, result.suspension.prompts()));
273+
emit(new AgentEvent.Finished(outcome));
224274
}
225-
}
226-
catch (Throwable error) {
227-
if (!cancelled) {
228-
subscriber.onError(error);
275+
else {
276+
// The output boundary: a completed delivery must match the declared
277+
// output schema, whatever path (fresh run or resume) produced it.
278+
validate(result.data.state, outputSchema, "output");
279+
AgentOutcome outcome = AgentOutcome.completed(result.data.messages, result.data.state,
280+
result.data.usage());
281+
emit(new AgentEvent.Finished(outcome));
229282
}
283+
subscriber.onComplete();
230284
}
231285
}
232-
233-
private ExecutionResult run() {
234-
context.control().assertActive();
235-
if (request.resumeToken() != null) {
236-
StoredContinuation stored = continuations.remove(request.resumeToken());
237-
if (stored == null || !stored.matches(context)) {
238-
throw new IllegalArgumentException("Unknown or unauthorized workflow resume token");
239-
}
240-
return stored.continuation.resume(request, context);
286+
catch (Throwable error) {
287+
if (!cancelled) {
288+
subscriber.onError(error);
241289
}
242-
RunData data = new RunData(request);
243-
return executeSteps(definition.steps(), 0, data, context);
244290
}
291+
}
292+
293+
private ExecutionResult run() {
294+
context.control().assertActive();
295+
if (request.resumeToken() != null) {
296+
StoredContinuation stored = continuations.remove(request.resumeToken());
297+
if (stored == null || !stored.matches(context)) {
298+
throw new IllegalArgumentException("Unknown or unauthorized workflow resume token");
299+
}
300+
// Inputs were validated on the fresh run that produced this continuation;
301+
// a resume request carries the continuation's state forward.
302+
return stored.continuation.resume(request, context);
303+
}
304+
RunData data = new RunData(request);
305+
// The input boundary: refuse before any step, tool or agent side effect.
306+
validate(data.inputs, inputSchema, "input");
307+
return executeSteps(definition.steps(), 0, data, context);
308+
}
245309

246310
private String register(Continuation continuation) {
247311
String token = definition.id() + ":" + definition.version() + ":" + UUID.randomUUID();
@@ -654,7 +718,9 @@ private static ExecutionResult suspended(RunData data, Map<String, Object> promp
654718
}
655719

656720
private ExecutionResult continueWith(Continuation next) {
657-
return new ExecutionResult(null, suspension, (request, context) -> {
721+
// The wrapper keeps the suspension-point snapshot: the suspended outcome is
722+
// built from this data before the continuation ever runs.
723+
return new ExecutionResult(data, suspension, (request, context) -> {
658724
ExecutionResult result = continuation.resume(request, context);
659725
return result.suspension == null ? next.resume(request, context) : result;
660726
});

‎argi-orchestration/argi-workflow-core/src/main/java/io/github/agentic/ai/workflow/WorkflowDefinitionValidator.java‎

Lines changed: 32 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,9 @@
1515
*/
1616
package io.github.agentic.ai.workflow;
1717

18+
import com.networknt.schema.SchemaRegistry;
19+
import com.networknt.schema.SpecificationVersion;
20+
1821
import java.util.ArrayList;
1922
import java.util.HashSet;
2023
import java.util.LinkedHashSet;
@@ -23,19 +26,25 @@
2326
import java.util.Set;
2427
import java.util.function.Function;
2528

26-
/** Structural validation performed before a definition can be published. */
29+
/**
30+
* Structural validation performed before a definition can be published.
31+
*
32+
* <p>
33+
* Declared input and output schemas are checked for syntax against the supported
34+
* JSON Schema dialect (draft 2020-12, the same validator the agent layer uses for
35+
* structured outputs). A definition that declares no schema is unaffected; a blank
36+
* schema is still rejected.
37+
*/
2738
public final class WorkflowDefinitionValidator {
2839

40+
private static final SchemaRegistry SCHEMAS = SchemaRegistry.withDefaultDialect(SpecificationVersion.DRAFT_2020_12);
41+
2942
private WorkflowDefinitionValidator() {
3043
}
3144

3245
public static void validate(WorkflowDefinition definition) {
33-
if (definition.inputSchema() != null && definition.inputSchema().isBlank()) {
34-
throw new IllegalArgumentException("inputSchema must not be blank");
35-
}
36-
if (definition.outputSchema() != null && definition.outputSchema().isBlank()) {
37-
throw new IllegalArgumentException("outputSchema must not be blank");
38-
}
46+
validateSchema("inputSchema", definition.inputSchema());
47+
validateSchema("outputSchema", definition.outputSchema());
3948
Set<String> ids = new HashSet<>();
4049
definition.steps().forEach(step -> validateStep(step, ids));
4150
}
@@ -108,6 +117,22 @@ else if (step instanceof WorkflowStep.Loop loop) {
108117
}
109118
}
110119

120+
private static void validateSchema(String field, String schema) {
121+
if (schema == null) {
122+
return;
123+
}
124+
if (schema.isBlank()) {
125+
throw new IllegalArgumentException(field + " must not be blank");
126+
}
127+
try {
128+
SCHEMAS.getSchema(schema);
129+
}
130+
catch (RuntimeException exception) {
131+
throw new IllegalArgumentException(
132+
field + " is not a valid JSON Schema (draft 2020-12): " + exception.getMessage(), exception);
133+
}
134+
}
135+
111136
private static void validateStep(WorkflowStep step, Set<String> ids) {
112137
if (!ids.add(step.id())) {
113138
throw new IllegalArgumentException("duplicate workflow step id: " + step.id());
Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
/*
2+
* Copyright 2026 the original author or authors.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* https://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
package io.github.agentic.ai.workflow;
17+
18+
import io.github.agentic.ai.agent.AgentResult;
19+
import java.util.List;
20+
21+
/**
22+
* A workflow input or output does not match the schema declared by the definition.
23+
* Carries one structured issue per violating location, so the caller can point at
24+
* the field and the error type instead of parsing a message.
25+
*/
26+
public class WorkflowValidationException extends WorkflowExecutionException {
27+
28+
private final List<AgentResult.OutputValidationIssue> issues;
29+
30+
public WorkflowValidationException(String message, List<AgentResult.OutputValidationIssue> issues) {
31+
super(message);
32+
this.issues = List.copyOf(issues);
33+
}
34+
35+
public List<AgentResult.OutputValidationIssue> issues() {
36+
return issues;
37+
}
38+
39+
}

0 commit comments

Comments
 (0)