LogicApps.Liquid
1.0.2
See the version list below for details.
dotnet add package LogicApps.Liquid --version 1.0.2
NuGet\Install-Package LogicApps.Liquid -Version 1.0.2
<PackageReference Include="LogicApps.Liquid" Version="1.0.2" />
<PackageVersion Include="LogicApps.Liquid" Version="1.0.2" />
<PackageReference Include="LogicApps.Liquid" />
paket add LogicApps.Liquid --version 1.0.2
#r "nuget: LogicApps.Liquid, 1.0.2"
#:package LogicApps.Liquid@1.0.2
#addin nuget:?package=LogicApps.Liquid&version=1.0.2
#tool nuget:?package=LogicApps.Liquid&version=1.0.2
Logic Apps Standard - Liquid validator and runner
la-liquid is a command line tool that validates Liquid maps and runs them exactly like the Azure Logic Apps Standard Liquid action, without deploying anything. It runs locally and in Azure DevOps pipelines.
> la-liquid validate --map Artifacts/Maps/customer.liquid --input samples/customer.json
Kind: JsonToJson (inferred)
Artifacts/Maps/customer.liquid(6,14): error LQ010: Filter 'upcase' does not exist in Logic Apps, use 'Upcase'. Logic Apps uses C# naming for filters and silently skips 'upcase', so the value is output unchanged.
Artifacts/Maps/customer.liquid(8,17): warning LQ021: Comparison with nil: in Logic Apps a JSON null value becomes an empty string, so it is not nil. ...
Validation failed: 1 map(s), 1 error(s), 1 warning(s).
Table of contents
- Why
- What Logic Apps really runs
- Installing
- Commands
- Diagnostics
- Where DotLiquid differs from Shopify Liquid
- Patterns found in real-world maps
- Related tools
- Test suites
- Azure DevOps
- VS Code and Visual Studio
- How conformance is verified
- Known limitations
Why
The Liquid that Logic Apps runs is not the Liquid in the Shopify documentation, and most mistakes do not fail the workflow run. They silently produce a wrong output:
| You write | Shopify Liquid | Logic Apps |
|---|---|---|
{{ name \| upcase }} |
SAHIN |
sahin: the filter is unknown and silently skipped |
{{ items \| where: "id", 1 }} |
filtered array | the unfiltered array: there is no where filter |
{% if value == nil %} for JSON null |
true | false: null becomes an empty string |
{{ 1.5 \| Times: 2 }} on a Dutch machine |
3 |
30: the decimal literal is parsed with the host culture |
{% include 'x' %} |
includes a file | writes Liquid error: ... into the output and succeeds |
la-liquid uses the same engine and the same settings as the runtime, and reports these problems with file, line and column.
What Logic Apps really runs
Established by decompiling the Logic Apps Standard workflow runtime (extension bundle Microsoft.Azure.Functions.ExtensionBundle.Workflows 1.170.91) and confirmed with the conformance tests:
- Engine: DotLiquid 2.0.361. The runtime's
DotLiquid.dllis byte-identical to thenetstandard1.3build of the NuGet package, which this tool pins. (The runtime also ships Fluid, but only the OpenAI connector uses it.) - Naming:
CSharpNamingConvention. Filters are PascalCase (Upcase,Date,Times,DividedBy,StripHtml). Tags stay lowercase (if,for,assign). - Custom tag:
{% JSONArrayFor item in collection [where Name] %}...{% endJSONArrayFor %}writes a comma between iterations. - Input: wrapped as
content.- JSON: parsed without date parsing (dates stay strings). Integers become
long, decimals becomedecimal,nullbecomes"". - XML: lookups use the local name only (namespaces are ignored), are case-insensitive, and return the first matching element.
- JSON: parsed without date parsing (dates stay strings). Integers become
- Rendering:
Template.Render(Hash). Render errors do not fail the action: they are written into the output asLiquid error: .... Missing values render as empty. - Output: for
JsonToJsonandXmlToJsonthe rendered text is parsed as JSON (Newtonsoft.Json 13.0.3), and invalid JSON fails the action. - Culture: decimal literals are parsed, and numbers and dates formatted, with the current culture of the host.
- Time zone:
Dateconverts dates with a time zone (Z,+02:00) to the host's local time and uses the host clock fornow. In Azure that is UTC, unless the app settingWEBSITE_TIME_ZONEis set. The tool emulates UTC by default; a plain run on a laptop in Central European Time would otherwise shift times by one or two hours.
Logic Apps Consumption
Microsoft documents that both Consumption (maps in an integration account) and Standard use DotLiquid 2.0.361 with the same C# filter names, JSONArrayFor and content wrapper. The tool works for Consumption maps in the same way.
The difference is in the evidence: the conformance tests run against the Standard runtime, because only that runtime can be installed locally. For Consumption, equality is documented by Microsoft, but not proven by the tests.
Consumption has no WEBSITE_TIME_ZONE app setting, so the default --time-zone UTC applies. The culture is assumed to be en-US, as for Standard.
Installing
| Way | Command or link | Needs |
|---|---|---|
| .NET tool from NuGet | dotnet tool install --global LogicApps.Liquid.Cli |
.NET 10 |
| Executable (Windows, Linux, macOS) | GitHub Releases | nothing |
| .NET library | dotnet add package LogicApps.Liquid |
.NET 10 |
| GitHub Action | uses: sahinozd/LogicAppsStandard.Liquid@v1.0.0 |
– |
| Azure DevOps step template | pipelines/templates/steps/validate-liquid-maps.yml | – |
The usage guide explains every way of installing, every command and option, test suites, Azure DevOps, GitHub Actions, VS Code and Visual Studio, and the .NET library.
Releases are created by the CI/CD workflow when a version tag (v1.2.3) is pushed. Each release includes:
- the NuGet packages, published to NuGet.org and GitHub Packages
- self-contained executables for Windows, Linux and macOS
- checksums
Commands
validate
Checks maps without writing anything.
la-liquid validate --map <file-or-folder> [--input <file>] [--kind <kind>] [engine options] [--warnings-as-errors]
- With a folder, every
*.liquidfile in it is checked (recursively). That's a good first step in a pipeline. - With an input, the map is also rendered and the output is checked: a dry run of
transform.
transform
Validates, renders and writes the output. The output file is only written when there are no errors.
la-liquid transform --map <file> --input <file> --output <file> [--kind <kind>] [--raw] [engine options] [--warnings-as-errors]
- JSON output is written indented, the way the Logic Apps run history shows it. Use
--rawto get the exact rendered text. - Kind: when
--kindis omitted it is inferred..xmlinput givesXmlTo*; a.jsonoutput gives*ToJsonand any other extension gives*ToText. Set it explicitly when it differs from your Liquid action.
test
Runs a test suite with expected outputs and writes a JUnit report.
la-liquid test --suite liquid-tests.json [--junit results.xml] [--update-expected] [engine options] [--warnings-as-errors]
Engine options
All commands accept these options:
| Option | Default | Meaning |
|---|---|---|
--culture |
en-US |
Culture of the Logic Apps host. DotLiquid uses it to parse decimal literals and text, and to format numbers and dates. |
--time-zone |
UTC |
Time zone of the Logic Apps host. Use the value of WEBSITE_TIME_ZONE when your Logic App sets it (Windows or IANA id). local uses this machine's time zone. |
--no-lint |
off | Skip the static checks. |
--no-deviations |
off | Skip the detection of filters that behave differently from Shopify Liquid (LQ1xx). |
For test, --culture and --time-zone override the culture and timeZone of the suite file.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Validation errors or failed tests |
| 2 | Invalid arguments, or a file could not be read or written |
Diagnostics
Findings use the MSBuild format file(line,col): error CODE: message, so Visual Studio, VS Code and Azure DevOps link them to the source. In Azure DevOps they are also logged with ##vso[task.logissue].
| Code | Severity | What |
|---|---|---|
| LQ001 | error | DotLiquid cannot parse the map; Logic Apps fails the action |
| LQ002 | error | Unknown tag, for example {% If %} (tags are case-sensitive) |
| LQ003 | error | Block never closed, or an end tag that doesn't match |
| LQ004 | error | {{ or {% never closed |
| LQ010 | error | Filter in Ruby/Shopify style (upcase, strip_html), silently skipped by Logic Apps |
| LQ011 | error | Unknown filter, silently skipped; for example | myProperty: value does not filter an array |
| LQ020 | warning | Variable used but never assigned (input fields are under content) |
| LQ021 | warning | Comparison with nil (JSON null is "" in Logic Apps) |
| LQ022 | error | include / extends: no template file system in Logic Apps |
| LQ023 | warning | A value was not found while rendering (for example a misspelled field); renders empty |
| LQ030 / LQ031 | error | Input is not valid JSON / XML |
| LQ040 | error | Render error; Logic Apps writes Liquid error: ... into the output |
| LQ041 | error | Output is not valid JSON for a *ToJson kind; Logic Apps fails the action |
| LQ042 | warning | The output is empty |
| LQ024 | warning | {% if content.x %} without a comparison: JSON null becomes "", which is truthy |
| LQ025 | warning | .@code, .$content, .#text or .ns0:x in a dot path: DotLiquid drops the character and reads another property |
| LQ026 | warning | if/unless/case directly inside JSONArrayFor: skipped items become undefined |
| LQ027 | warning | Plus: 0 / Times: 1 used as a text-to-number conversion: on text it joins or repeats |
| LQ028 | warning | Empty search text in Replace/Remove, for example '''' meant as an escaped apostrophe: does nothing |
| LQ043 | warning | The JSON output contains empty array items, which become undefined |
| LQ100–LQ128 | warning | A filter behaves differently from Shopify Liquid, see Where DotLiquid differs from Shopify Liquid |
Where DotLiquid differs from Shopify Liquid
DotLiquid's filters don't always behave like the original Ruby implementation, especially with numbers and decimals. Most of these differences don't fail the workflow; they silently change the output.
validate --input and transform detect them with the actual values:
- How: the map is rendered a second time. In that second render, each relevant filter is wrapped in an observer that records its real input and then calls the original DotLiquid filter.
- What you get: each warning has the line and column of the filter call, the actual result and the Shopify Liquid result.
- Your output is not affected: the output always comes from the normal render, and the tests verify that both renders give identical text.
A few checks also run without input (LQ024–LQ028, LQ112, LQ118, LQ120).
Every result below was confirmed on the real Logic Apps engine (conformance tests) and compared with the Shopify Liquid source.
| Code | Example | Logic Apps | Shopify Liquid |
|---|---|---|---|
| LQ100 | "2026" \| Plus: 10 (also after Date: "yyyy") |
202610: text is joined |
2036 |
| LQ101 | "2026" \| Times: 3 |
202620262026: text is repeated (negative fails) |
6078 |
| LQ102 | "2026" \| Minus: 1 (also DividedBy, Modulo) |
Liquid error: Parameter count mismatch. |
2025 |
| LQ103 | "125,50" \| Times: 1.0 |
12550 on en-US: text is parsed with the host culture |
125.0 (to_i stops at the comma) |
| LQ105 | "2026" \| Times: 1.0 \| Append: "-12-31" |
2026.0-12-31: trailing zeros kept in text filters ({{ }} shows 2026) |
2026.0-12-31 |
| LQ106 | 2.5 \| Round |
2: banker's rounding |
3 |
| LQ107 | "abc" \| Round |
empty | 0 |
| LQ108 | -7 \| DividedBy: 2 |
-3: truncates |
-4: floors |
| LQ109 | -7 \| Modulo: 3 |
-1 |
2 |
| LQ110 | 1.5 \| DividedBy: 0 |
∞ |
error |
| LQ111 | false \| Default: "x" / " " \| Default: "x" |
False / x |
x / " " |
| LQ112 | "1.234.5" \| Replace: ".", "," (also ReplaceFirst, RemoveFirst) |
,,,,,,,: search text is a regular expression |
1,234,5 |
| LQ113 | "a,,b" \| Split: "," / "abc" \| Split: "" |
2 items / 1 item | 3 items / 3 items |
| LQ114 | nil \| Append: "x" |
empty | x |
| LQ115 | "hELLO wORLD" \| Capitalize |
HELLO WORLD |
Hello world |
| LQ116 | "café" \| Escape |
café |
café |
| LQ117 | items \| Sort: "n" on JSON or XML input / ["b","A","a"] \| Sort |
not sorted / a,A,b (culture order) |
sorted / A,a,b |
| LQ118 | "2026-10-15T23:30:00Z" \| Date: "HH:mm" |
converted to the host time zone | keeps the time zone |
| LQ119 | "03/04/2026" \| Date: "yyyy-MM-dd" |
2026-03-04 on en-US, 2026-04-03 on nl-NL |
2026-04-03 |
| LQ120 | Date: "%Y-%m-%d" |
Y-0-15: .NET format strings |
2026-10-15 |
| LQ121 | "not a date" \| Date: "yyyy" |
returned unchanged | returned unchanged |
| LQ122 | "now" \| Date: "yyyy" |
host clock and time zone | server clock |
| LQ123 | "abc" \| Abs / "abc" \| AtLeast: 3 |
0 / abc |
0 / 3 |
| LQ124 | 12345 \| Size |
0 |
8 |
| LQ125 | ["x","x","y"] \| Uniq |
x,y: reported because Uniq is often used as an array wrapper (see below) |
x,y |
| LQ126 | {% for x in singleObject %} |
renders nothing | iterates the hash |
| LQ127 | {{ content.address }} / {{ content.items }} (objects) |
nothing / Microsoft.Azure.Function.Common.JObjectDrop… |
the hash / array as text |
| LQ128 | content.Root.Packages \| Sort: "Weight" (also Compact, Uniq) on XML elements |
the elements are flattened into all their child values (12.5, 2, 3.75, 1) |
sorted elements |
The working conversion from text to a whole number is | Times: 1.0 | Round, for example {{ "2026" | Times: 1.0 | Round | Plus: 10 }} gives 2036.
Two rules keep the warnings useful:
- Backslash escapes: a
Replacesearch text with a backslash escape ('\\','\.') is treated as an intentional regular expression and isn't flagged.Replace: '\\', '\\'correctly escapes backslashes for JSON because DotLiquid uses regular expressions. - Trailing zeros (LQ105): reported only where such a value reaches a text filter, not when it's written to the output directly.
Use --no-lint to see only what the Logic Apps engine itself reports (LQ001, LQ023 and up).
Patterns found in real-world maps
To test the checks on real code, I ran the tool on a large set of production Liquid maps from several Logic Apps integration platforms, both Standard and Consumption. I read their comments for workarounds and verified each pattern on the real Logic Apps engine.
The patterns below are generalised: names and values are examples, not taken from the maps. They come up again and again in practice; each one is now flagged, together with the working alternative.
| Pattern | What actually happens in Logic Apps | Code | Use instead |
|---|---|---|---|
\| Times: 1.0 (with a decimal, not 1) to make text numeric |
Works, but the result is a decimal (2026.0) once it reaches a text filter |
LQ105 | \| Times: 1.0 \| Round for whole numbers |
\| Plus: 0 or \| Times: 1 to make text numeric |
On text: "123" \| Plus: 0 gives 1230; Times: 1 leaves it text |
LQ027, LQ100, LQ101 | \| Times: 1.0 (\| Round) |
\| Round: n to make text numeric, with n counted from the decimals |
Works, but text is parsed with the host culture, and halves round to even | LQ103, LQ106 | \| Times: 1.0 |
\| Times: -1 and then Plus, as a replacement for Minus |
Minus on text fails; Plus on text joins ("2026" \| Plus: -45 gives 2026-45) |
LQ100, LQ102 | Convert first: \| Times: 1.0 \| Round \| Minus: 45 |
x \| Concat: x \| Uniq to turn "one object or an array" into an array |
Concat doesn't exist and is skipped; Uniq does the wrapping, and removes duplicate values |
LQ011, LQ125 | \| Compact: wraps without removing duplicates |
{% for x in content.element %} where the XML had one element |
XML converted to JSON gives an object for a single element, not an array: the loop renders nothing | LQ126 | {% assign items = content.element \| Compact %} |
{% if x.first %} to tell an array from an object |
Works: .first of an object is empty |
– | Keep, or simply use \| Compact |
JSONArrayFor with an if inside; replaced by a for with manual commas and code that removes the last comma |
JSONArrayFor also writes a comma for skipped items; the JSON gets undefined items |
LQ026, LQ043 | Select the items first, then loop over the selection |
content.item.@code, .$content, .#text (names from XML converted to JSON) |
The special character is dropped, so another property is read, without any error | LQ025 | content.item["@code"] |
\| Replace: '''' ,''' to escape an apostrophe for XML |
'''' is two empty strings: nothing is replaced |
LQ028 | \| Replace: "'", ''' |
\| Replace: '\\', '\\' \| Replace: '"', '\"' to escape text for JSON |
Correct and needed: DotLiquid has no JSON escape filter. Because Replace uses a regular expression, '\\' matches one backslash |
– (not flagged) | Keep it for every text value written into JSON |
\| Date: "yyyy-MM-ddTHH:mm:ssZ" |
Prints a literal Z after a time that is converted to the host time zone; only correct while the Logic App runs in UTC |
LQ118 | K for the real offset, or keep the app in UTC |
\| Append: ' ' \| Truncate: 5, '' to pad text to a fixed length |
Works the same as in Shopify Liquid (there is no pad filter) | – | Keep |
\| type: 'A' (a property name used as a filter) to select array items |
Unknown filters are skipped: nothing is selected, and [0] is just the first item |
LQ011 | A for loop with an if |
{{ content \| Json }} to include the whole message, for example in a notification |
Json doesn't exist and is skipped; an object prints nothing, so the message never ends up in the output |
LQ011, LQ127 | Print the fields, or pass the JSON as text in the input of the Liquid action |
\| Abs \| Times: 100 to convert text to a number |
Works, but drops the minus sign ("-1.5" gives 150) and gives 0 for text that isn't a number |
LQ027, LQ123 | \| Times: 1.0 \| Times: 100 |
{% if x != null %} to skip empty input |
JSON null becomes "", which isn't nil: the condition is true for null values |
LQ021 | {% if x != null and x != "" %} |
Related tools
There are tools that render DotLiquid 2.0.361 templates:
- LiquidTester: browser-based
- DotLiquid Debugger: VS Code preview and step debugger
- Older CLI renderers such as LiquidTransformation
They are useful for seeing the output while you write a map.
la-liquid adds what none of them does:
- Same as Logic Apps: it reproduces the Logic Apps engine setup, including culture and time zone, and proves equality with the real runtime in conformance tests.
- Checks and warnings: it finds Logic Apps pitfalls (silently skipped filters,
nullhandling, special characters in paths), and the deviations from Shopify Liquid using the actual values. - Pipelines: it gives exit codes, file and line findings, test suites and JUnit reports.
Some deviations are known in the DotLiquid project itself, for example Replace uses regular expressions and the missing json filter.
Test suites
A test suite pins a map's behaviour to known outputs, which is useful as a regression test in a pipeline. Paths are relative to the suite file.
{
"culture": "en-US",
"timeZone": "UTC",
"warningsAsErrors": false,
"tests": [
{
"name": "Orders to shipment request",
"map": "../Artifacts/Maps/orders.to.shipment.liquid",
"input": "inputs/orders.json",
"kind": "JsonToJson",
"expectedOutput": "expected/shipment.json"
},
{
"name": "Known Logic Apps behaviour is accepted",
"map": "../Artifacts/Maps/legacy.liquid",
"input": "inputs/legacy.json",
"expectedDiagnostics": [ "LQ021" ]
}
]
}
- Output comparison: JSON outputs are compared structurally. Text outputs are compared line by line, ignoring line endings.
expectedDiagnostics: these codes must be reported, and they don't fail the test.--update-expected: writes the actual outputs into the expected files. Review the changes before you commit them.
See samples/liquid-tests.json for a working suite.
Azure DevOps
pipelines/templates/steps/validate-liquid-maps.yml installs the tool, validates all maps of a Logic App and runs a test suite. Findings appear on the run summary, and test results on the Tests tab.
steps:
- template: templates/steps/validate-liquid-maps.yml
parameters:
mapsFolder: '$(Build.SourcesDirectory)/src/LogicApp/Artifacts/Maps'
testSuite: '$(Build.SourcesDirectory)/tests/Liquid/liquid-tests.json'
warningsAsErrors: false
toolFeed: 'https://pkgs.dev.azure.com/<org>/_packaging/<feed>/nuget/v3/index.json' # optional
pipelines/azure-pipelines.yml builds this repository. It runs the unit and conformance tests against a workflow bundle downloaded from the public Azure Functions CDN, then packs the tool.
VS Code and Visual Studio
Open the folder in VS Code or LogicAppsStandard.Liquid.slnx in Visual Studio.
The VS Code tasks (Terminal → Run Task):
- la-liquid: validate current map: validates the open
.liquidfile; findings show up in the Problems panel. - la-liquid: transform current map: asks for an input and output file.
- la-liquid: test samples, plus build and test.
There are also two launch configurations to debug the CLI.
How conformance is verified
tests/Liquid.ConformanceTests loads the real Logic Apps Liquid engine (LiquidTransformer from Microsoft.Azure.Workflows.Integration.Edge.dll) from the workflow extension bundle, in an isolated AssemblyLoadContext. It then runs every case through both engines, for both the en-US and nl-NL cultures. A case passes only when the outputs are identical, or both engines fail.
- Where the bundle comes from: locally it is the bundle installed by the Azure Logic Apps (Standard) VS Code extension, found under
%USERPROFILE%\.azure-functions-core-tools\Functions\ExtensionBundles. SetLOGICAPPS_WORKFLOW_BUNDLE_BINto use anotherbinfolder. - No bundle: the tests are reported as ignored.
- When a new bundle ships: run the conformance tests against it before trusting the tool with it.
Known limitations
- Deviation detection needs input: the LQ1xx checks run while rendering, so they only see the values in your test input. A filter that is never reached, or never gets a problem value, isn't reported.
- One transform at a time per process: DotLiquid's configuration and the emulated time zone (set through .NET's time zone cache) are process-wide. The library therefore runs transforms in one process one at a time. Use several processes for parallel work.
- XML is read as UTF-8: Logic Apps loads XML from the bytes of the message, and the tool does the same with the UTF-8 text of the file. A file in UTF-16 is not supported, and an XML declaration with
encoding="utf-16"on UTF-8 content is reported as invalid, just as Logic Apps rejects it. - Culture of the Azure host: the default
en-USis an assumption. To verify it for your environment, deploy a workflow with a Liquid action rendering{{ 1.5 | Times: 2 }}.3means en-US style parsing. - Static checks are heuristic: they work on the template text. The variable checks (LQ020) can miss usages in unusual expressions. The engine checks (LQ001, LQ023, LQ040, LQ041) come from DotLiquid itself.
- No output schema validation: the Liquid action's optional output JSON schema is not supported yet.
- The
$contentenvelope: XML input is read from a plain XML file. Base64 content envelopes are not supported as input files.
License
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- DotLiquid (= 2.0.361)
- Newtonsoft.Json (= 13.0.3)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.