π« Toolkit to help you get started with SDD or any other process!
docs(workflows): correct filtered-count comparison guidance (#5148)
WOLIKIMCHENGf4a91f5e8c11
diff --git a/docs/reference/workflows.md b/docs/reference/workflows.mdindex a24b700a2..cb4bc1fa9 100644--- a/docs/reference/workflows.md+++ b/docs/reference/workflows.md@@ -1204,7 +1204,13 @@ Notes on the newer filters:- **`to_json` output is deterministic.** Object keys are sorted and non-ASCII characters are left as-is rather than escaped, so the same value always serializes to the same bytes. That buys reproducibility only β it does **not** make the result safe to pass through a shell, because [interpolation adds no quoting or escaping](#interpolation-and-shell-safety). Do not interpolate unconstrained JSON into a `run` field.- **`to_json` rejects non-finite floats.** `NaN`, `Infinity`, and `-Infinity` raise a `ValueError` naming `to_json` instead of serializing to bare tokens. None of the three is valid JSON, so emitting them would hand a standards-compliant downstream parser a string it must reject.- **`to_json` requires string mapping keys.** JSON objects have string keys, so a mapping with any other key type β `{1: "a"}`, `{True: "a"}` β raises a `ValueError` naming the key type instead. Left to `json.dumps`, an integer key would be coerced to `"1"` and collide with an existing `"1"` key, while mixed key types would fail `sort_keys` with an ordering `TypeError` reported only as "not JSON-serializable".-- **Trailing comparisons after a filter are rejected.** The parser splits on the top-level `|` before looking for operators, so `{{ items | length > 0 }}` raises rather than evaluating. The count does not exist until `length` runs, so there is no way to write that comparison; the supported branching form is the filter's own truthiness in a `condition:`, since `length` returns `0` for an empty input:+- **Comparing filtered counts requires parentheses.** The parser splits on the top-level `|` before looking for operators, so an unparenthesized trailing comparison such as `{{ inputs.items | length > 0 }}` raises a `ValueError`. Parenthesize the filtered operand to compare its result: `{{ (inputs.items | length) > 0 }}`. For a threshold of at least two:++ ```yaml+ condition: "{{ (inputs.items | length) >= 2 }}"+ ```++ For an emptiness check, use the filtered count's truthiness directly:```yamlcondition: "{{ inputs.items | length }}" # 0 is False, any non-zero count is Truediff --git a/workflows/ARCHITECTURE.md b/workflows/ARCHITECTURE.mdindex c06d28018..1ce065778 100644--- a/workflows/ARCHITECTURE.md+++ b/workflows/ARCHITECTURE.md@@ -212,7 +212,13 @@ The older filters are more permissive and are unchanged: `join` stringifies unsu**`to_json` output is deterministic.** It pins `sort_keys=True` and `ensure_ascii=False`, so the same value always serializes to the same bytes regardless of dict insertion order or platform, and non-ASCII text is not `\uXXXX`-escaped. This buys reproducibility only β it does **not** make the result safe to pass through a shell, because expression interpolation adds no quoting or escaping. See [Interpolation and shell safety](../docs/reference/workflows.md#interpolation-and-shell-safety) before interpolating JSON into a `run` field.-**Filters and comparisons.** The parser splits on the top-level `|` before looking for operators, so a comparison or other trailing token after a filter is rejected as ambiguous rather than silently evaluated (`{{ items | default(0) > 5 }}` raises) β the same holds for the new filters. The count a `length` filter would produce does not exist before the filter runs, so there is no way to write `{{ items | length > 0 }}`; the only supported branching form is the filtered value's own truthiness in a `condition:`, since `length` returns `0` for an empty input:+**Filters and comparisons.** The parser splits on the top-level `|` before looking for operators, so an unparenthesized trailing comparison such as `{{ inputs.items | length > 0 }}` raises a `ValueError`. Parenthesize the filtered operand to compare its result: `{{ (inputs.items | length) > 0 }}`. For a threshold of at least two:++```yaml+condition: "{{ (inputs.items | length) >= 2 }}"+```++For an emptiness check, use the filtered count's truthiness directly:```yamlcondition: "{{ inputs.items | length }}" # 0 -> False, any non-zero count -> True