FlowDrop Workflow Specification 1.0-draft

A model's tool arguments are normalized against the tool's own schema

Models hand back arguments that are nearly right: a JSON array as a string, a value escaped twice. Normalization repairs exactly the cases the tool's own schema can vouch for, and leaves the rest for validation to report honestly.

The rule

Normative: this is the rule
  1. Before a tool is invoked, the arguments a model supplied are reconciled with the tool's declared input schema.
  2. A string argument is decoded as JSON only where all three hold: the schema declares that parameter array or object, the string parses as JSON, and the parsed shape matches what was declared: a list for array, a map for object.
  3. A parameter declared string is never decoded, and a parsed value of the wrong shape is never substituted; an argument that fails any of the three is passed through unmodified.
  4. Independently, every string leaf of an argument has its HTML character references decoded, repeated until the value stops changing so that a doubly-escaped value resolves fully rather than one level short; an implementation may bound the number of passes.
  5. Keys are never modified, and text containing no character reference is returned unchanged.

What it means

The two repairs are independent and run on different things. JSON-string decoding looks only at whether the tool's own schema declares that parameter array or object, and only fires when the parsed result actually has that shape — a string that parses as JSON but produces the wrong shape (an object where the schema declares an array) is left exactly as sent, never coerced or substituted. Entity decoding, by contrast, runs on every string leaf regardless of what the schema declares, repeating until the value stops changing, so a doubly-escaped value resolves fully rather than stopping one level short. Keys are never touched by either repair.

Example

A title argument arrives HTML-escaped twice over:

A doubly-escaped title argumentsent
{ "title": "Ember & Oak" }
What reaches the tooldecoded
{ "title": "Ember & Oak" }

An object literal sent for a parameter the schema declares array is left untouched rather than substituted into the wrong shape:

An object literal where the schema declares an arraysent
{ "ops": "{\"op\":\"add\"}" }

References

Normative: incorporated into this rule

Rule identifiers are permanent and are never renumbered. Each implementation publishes its own standing against these rules; this specification does not.spec 1.0-draft · RT-TOOL-8 · changed in spec 1.0