ValidFilterArgumentTypes

Last edit: Aug 14, 2026

ValidFilterArgumentTypes

Severity: warning | Type: LiquidHtml

This check ensures that a value passed to a Liquid filter has the type the platformOS documentation publishes for it. It is the filter counterpart of ValidTagArgumentTypes and shares the same type inference and the same compatibility rules.

The piped value is checked too, because the documentation publishes it as the filter's first argument — the same way arity counts it. That is where the mistake this check exists for usually is:


{{ 123 | hash_add_key: 'hello', 'world' }}

platformOS answers that with hash_add_key filter - first argument must be a hash, received: 123 and the page returns a 500, so a published type here is a contract the runtime enforces rather than a hint.

What is and is not reported

The expected types come from the Liquid filters reference and from nowhere else. platformOS Check never guesses a type. A value is only reported when:

The filter is documented with a parameters entry for that position or name.
That entry publishes a real type rather than untyped.
The value is a literal, or an expression ending in a filter whose return type the documentation publishes — a bare variable lookup ({{ maybe_a_hash | hash_keys }}) cannot be typed without running the code and is never reported.

untyped means any type is accepted, and it is how the documentation says so. Every argument of every filter Liquid itself provides is untyped, because those coerce rather than refuse — {{ 5 | upcase }} renders 5, {{ '5' | minus: 1 }} renders 4, {{ h | round }} renders 0 — so nothing is reported about them. The platform's own filters mostly do refuse, and those are the ones this check can speak about.

A parameter may also name several types, and then a value is only reported when it matches none of them. strftime accepts a string, a number of seconds, a Date or a Time and raises on anything else, so all four are published and all four pass.

`object` means a Hash

On a filter parameter, object is the Hash spelling and an array is not one:


{% assign list = 'a,b' | split: ',' %}
{{ list | hash_add_key: 'hello', 'world' }}

is hash_add_key filter - first argument must be a hash, received: ["a", "b"] at render time, and is reported. A filter that takes either publishes both — to_xml and www_form_encode are object, array — so {{ list | to_xml }} is correct and silent. Note this differs from object in a {% doc %} block, where it means "some structured value" and does accept an array.

Two more silences worth knowing:

nil is accepted for every type — it means "no value", not a wrong one.
A variadic parameter gathers every remaining argument, so its published type describes the collection while each argument written at the call site is an element of it. {{ hash | hash_dig: 'a', 'b' }} passes two strings to a parameter published as an array, and is correct.

Examples

✗ Incorrect Code Example (Avoid using this):


{{ 123 | hash_add_key: 'hello', 'world' }}

{{ 'a,b,c' | array_add: 'd' }}

{{ hash | hash_add_key: 5, 'world' }}

✓ Correct Code Example (Use this instead):


{% assign hash = {"hello": "world"} %}
{{ hash | hash_add_key: 'goodbye', 'world' }}

{% assign array = 'a,b,c' | split: ',' %}
{{ array | array_add: 'd' }}

{% comment %}A filtered value is typed by its last filter{% endcomment %}
{{ payload | parse_json | hash_keys }}

{% comment %}A bare variable is never reported — its type is unknown here{% endcomment %}
{{ maybe_a_hash | hash_keys }}

Configuration

The default configuration for this check:

ValidFilterArgumentTypes:
  enabled: true
  severity: warning

Disabling This Check

This check is safe to disable if you rely on a filter coercing a value to the type it needs. Note that the platform's own filters generally do not coerce — they raise Liquid::ArgumentError, which fails the whole page.

ValidFilterArgumentTypes