Schema reference for Workflow Definition Language in Azure Logic Apps

When you create a logic app workflow with Azure Logic Apps, your workflow's underlying definition describes the actual logic that runs for your logic app. This description follows a structure that's defined and validated by the Workflow Definition Language schema, which uses JavaScript Object Notation (JSON).

Workflow definition structure

A workflow definition has at least one trigger that instantiates your logic app, plus one or more actions that your logic app runs.

Here is the high-level structure for a workflow definition:

"definition": {
  "$schema": "<workflow-definition-language-schema-version>",
  "contentVersion": "<workflow-definition-version-number>",
  "parameters": { "<workflow-parameter-definitions>" },
  "triggers": { "<workflow-trigger-definitions>" },
  "actions": { "<workflow-action-definitions>" },
  "outputs": { "<workflow-output-definitions>" }
}
Element Required Description
definition Yes The starting element for your workflow definition
$schema Only when externally referencing a workflow definition The location for the JSON schema file that describes the Workflow Definition Language version, which you can find here:

https://schema.management.azure.com/schemas/2016-06-01/Microsoft.Logic.json

contentVersion No The version number for your workflow definition, which is "1.0.0.0" by default. To help identify and confirm the correct definition when deploying a workflow, specify a value to use.
parameters No The definitions for one or more parameters that pass data into your workflow

Maximum parameters: 50

triggers No The definitions for one or more triggers that instantiate your workflow. You can define more than one trigger, but only with the Workflow Definition Language, not visually through the Logic Apps Designer.

Maximum triggers: 10

actions No The definitions for one or more actions to execute at workflow runtime

Maximum actions: 250

outputs No The definitions for the outputs that return from a workflow run

Maximum outputs: 10

Parameters

In the parameters section, define all the workflow parameters that your logic app uses at deployment for accepting inputs. Both parameter declarations and parameter values are required at deployment. Before you can use these parameters in other workflow sections, make sure that you declare all the parameters in these sections.

Here is the general structure for a parameter definition:

"parameters": {
  "<parameter-name>": {
    "type": "<parameter-type>",
    "defaultValue": "<default-parameter-value>",
    "allowedValues": [ <array-with-permitted-parameter-values> ],
    "metadata": { 
      "key": { 
        "name": "<key-value>"
      } 
    }
  }
},
Element Required Type Description
type Yes int, float, string, securestring, bool, array, JSON object, secureobject

Note: For all passwords, keys, and secrets, use the securestring and secureobject types because the GET operation doesn't return these types.

The type for the parameter
defaultValue No Same as type The default parameter value when no value is specified when the workflow instantiates
allowedValues No Same as type An array with values that the parameter can accept
metadata No JSON object Any other parameter details, for example, the name or a readable description for your logic app, or design-time data used by Visual Studio or other tools

Triggers and actions

In a workflow definition, the triggers and actions sections define the calls that happen during your workflow's execution. For syntax and more information about these sections, see Workflow triggers and actions.

Outputs

In the outputs section, define the data that your workflow can return when finished running. For example, to track a specific status or value from each run, specify that the workflow output returns that data.

Note

When responding to incoming requests from a service's REST API, do not use outputs. Instead, use the Response action type. For more information, see Workflow triggers and actions.

Here is the general structure for an output definition:

"outputs": {
  "<key-name>": {  
    "type": "<key-type>",  
    "value": "<key-value>"  
  }
} 
Element Required Type Description
<key-name> Yes String The key name for the output return value
type Yes int, float, string, securestring, bool, array, JSON object The type for the output return value
value Yes Same as type The output return value

To get the output from a workflow run, review the logic app's run history and details in the Azure portal or use the Workflow REST API. You can also pass output to external systems, for example, Power BI so that you can create dashboards.

Expressions

With JSON, you can have literal values that exist at design time, for example:

"customerName": "Sophia Owen", 
"rainbowColors": ["red", "orange", "yellow", "green", "blue", "indigo", "violet"], 
"rainbowColorsCount": 7 

You can also have values that don't exist until run time. To represent these values, you can use expressions, which are evaluated at run time. An expression is a sequence that can contain one or more functions, operators, variables, explicit values, or constants. In your workflow definition, you can use an expression anywhere in a JSON string value by prefixing the expression with the at-sign (@). When evaluating an expression that represents a JSON value, the expression body is extracted by removing the @ character, and always results in another JSON value.

For example, for the previously defined customerName property, you can get the property value by using the parameters() function in an expression and assign that value to the accountName property:

"customerName": "Sophia Owen", 
"accountName": "@parameters('customerName')"

String interpolation also lets you use multiple expressions inside strings that are wrapped by the @ character and curly braces ({}). Here is the syntax:

@{ "<expression1>", "<expression2>" }

The result is always a string, making this capability similar to the concat() function, for example:

"customerName": "First name: @{parameters('firstName')} Last name: @{parameters('lastName')}"

If you have a literal string that starts with the @ character, prefix the @ character with another @ character as an escape character: @@

These examples show how expressions are evaluated:

JSON value Result
"Sophia Owen" Return these characters: 'Sophia Owen'
"array[1]" Return these characters: 'array[1]'
"@@" Return these characters as a one-character string: '@'
" @" Return these characters as a two-character string: ' @'

For these examples, suppose you define "myBirthMonth" equal to "January" and "myAge" equal to the number 42:

"myBirthMonth": "January",
"myAge": 42

These examples show how the following expressions are evaluated:

JSON expression Result
"@parameters('myBirthMonth')" Return this string: "January"
"@{parameters('myBirthMonth')}" Return this string: "January"
"@parameters('myAge')" Return this number: 42
"@{parameters('myAge')}" Return this number as a string: "42"
"My age is @{parameters('myAge')}" Return this string: "My age is 42"
"@concat('My age is ', string(parameters('myAge')))" Return this string: "My age is 42"
"My age is @@{parameters('myAge')}" Return this string, which includes the expression: "My age is @{parameters('myAge')}`

When you're working visually in the Logic Apps Designer, you can create expressions through the Expression builder, for example:

Logic Apps Designer > Expression builder

When you're done, the expression appears for the corresponding property in your workflow definition, for example, the searchQuery property here:

"Search_tweets": {
  "inputs": {
    "host": {
      "connection": {
       "name": "@parameters('$connections')['twitter']['connectionId']"
      }
    }
  },
  "method": "get",
  "path": "/searchtweets",
  "queries": {
    "maxResults": 20,
    "searchQuery": "Azure @{concat('firstName','', 'LastName')}"
  }
},

Operators

In expressions and functions, operators perform specific tasks, such as reference a property or a value in an array.

Operator Task
' To use a string literal as input or in expressions and functions, wrap the string only with single quotation marks, for example, '<myString>'. Do not use double quotation marks (""), which conflict with the JSON formatting around an entire expression. For example:

Yes: length('Hello')
No: length("Hello")

When you pass arrays or numbers, you don't need wrapping punctuation. For example:

Yes: length([1, 2, 3])
No: length("[1, 2, 3]")

[] To reference a value at a specific position (index) in an array, use square brackets. For example, to get the second item in an array:

myArray[1]

. To reference a property in an object, use the dot operator. For example, to get the name property for a customer JSON object:

"@parameters('customer').name"

? To reference null properties in an object without a runtime error, use the question mark operator. For example, to handle null outputs from a trigger, you can use this expression:

@coalesce(trigger().outputs?.body?.<someProperty>, '<property-default-value>')

Functions

Some expressions get their values from runtime actions that might not yet exist when a logic app starts to run. To reference or work with these values in expressions, you can use functions. For example, you can use math functions for calculations, such as the add() function, which returns the sum from integers or floats. For detailed information about each function, see the alphabetical reference article. Or, continue learning about functions and their general purpose.

Here are just a couple example tasks that you can perform with functions:

Task Function syntax Result
Return a string in lowercase format. toLower('<text>')

For example: toLower('Hello')

"hello"
Return a globally unique identifier (GUID). guid() "c2ecc88d-88c8-4096-912c-d6f2e2b138ce"

This example shows how you can get the value from the customerName parameter and assign that value to the accountName property by using the parameters() function in an expression:

"accountName": "@parameters('customerName')"

Here are some other general ways that you can use functions in expressions:

Task Function syntax in an expression
Perform work with an item by passing that item to a function. "@<functionName>(<item>)"
1. Get the parameterName's value by using the nested parameters() function.
2. Perform work with the result by passing that value to functionName.
"@<functionName>(parameters('<parameterName>'))"
1. Get the result from the nested inner function functionName.
2. Pass the result to the outer function functionName2.
"@<functionName2>(<functionName>(<item>))"
1. Get the result from functionName.
2. Given that the result is an object with property propertyName, get that property's value.
"@<functionName>(<item>).<propertyName>"

For example, the concat() function can take two or more string values as parameters. This function combines those strings into one string. You can either pass in string literals, for example, "Sophia" and "Owen" so that you get a combined string, "SophiaOwen":

"customerName": "@concat('Sophia', 'Owen')"

Or, you can get string values from parameters. This example uses the parameters() function in each concat() parameter and the firstName and lastName parameters. You then pass the resulting strings to the concat() function so that you get a combined string, for example, "SophiaOwen":

"customerName": "@concat(parameters('firstName'), parameters('lastName'))"

Either way, both examples assign the result to the customerName property.

For detailed information about each function, see the alphabetical reference article. Or, continue learning about functions based on their general purpose.

String functions

To work with strings, you can use these string functions and also some collection functions. String functions work only on strings.

String function Task
concat Combine two or more strings, and return the combined string.
endsWith Check whether a string ends with the specified substring.
guid Generate a globally unique identifier (GUID) as a string.
indexOf Return the starting position for a substring.
lastIndexOf Return the ending position for a substring.
replace Replace a substring with the specified string, and return the updated string.
split Return an array that has all the characters from a string and separates each character with the specific delimiter character.
startsWith Check whether a string starts with a specific substring.
substring Return characters from a string, starting from the specified position.
toLower Return a string in lowercase format.
toUpper Return a string in uppercase format.
trim Remove leading and trailing whitespace from a string, and return the updated string.

Collection functions

To work with collections, generally arrays, strings, and sometimes, dictionaries, you can use these collection functions.

Collection function Task
contains Check whether a collection has a specific item.
empty Check whether a collection is empty.
first Return the first item from a collection.
intersection Return a collection that has only the common items across the specified collections.
join Return a string that has all the items from an array, separated by the specified character.
last Return the last item from a collection.
length Return the number of items in a string or array.
skip Remove items from the front of a collection, and return all the other items.
take Return items from the front of a collection.
union Return a collection that has all the items from the specified collections.

Comparison functions

To work with conditions, compare values and expression results, or evaluate various kinds of logic, you can use these comparison functions. For the full reference about each function, see the alphabetical reference article.

Comparison function Task
and Check whether all expressions are true.
equals Check whether both values are equivalent.
greater Check whether the first value is greater than the second value.
greaterOrEquals Check whether the first value is greater than or equal to the second value.
if Check whether an expression is true or false. Based on the result, return a specified value.
less Check whether the first value is less than the second value.
lessOrEquals Check whether the first value is less than or equal to the second value.
not Check whether an expression is false.
or Check whether at least one expression is true.

Conversion functions

To change a value's type or format, you can use these conversion functions. For example, you can change a value from a Boolean to an integer. To learn how Logic Apps handles content types during conversion, see Handle content types. For the full reference about each function, see the alphabetical reference article.

Conversion function Task
array Return an array from a single specified input. For multiple inputs, see createArray.
base64 Return the base64-encoded version for a string.
base64ToBinary Return the binary version for a base64-encoded string.
base64ToString Return the string version for a base64-encoded string.
binary Return the binary version for an input value.
bool Return the Boolean version for an input value.
createArray Return an array from multiple inputs.
dataUri Return the data URI for an input value.
dataUriToBinary Return the binary version for a data URI.
dataUriToString Return the string version for a data URI.
decodeBase64 Return the string version for a base64-encoded string.
decodeDataUri Return the binary version for a data URI.
decodeUriComponent Return a string that replaces escape characters with decoded versions.
encodeUriComponent Return a string that replaces URL-unsafe characters with escape characters.
float Return a floating point number for an input value.
int Return the integer version for a string.
json Return the JavaScript Object Notation (JSON) type value or object for a string or XML.
string Return the string version for an input value.
uriComponent Return the URI-encoded version for an input value by replacing URL-unsafe characters with escape characters.
uriComponentToBinary Return the binary version for a URI-encoded string.
uriComponentToString Return the string version for a URI-encoded string.
xml Return the XML version for a string.

Math functions

To work with integers and floats, you can use these math functions. For the full reference about each function, see the alphabetical reference article.

Math function Task
add Return the result from adding two numbers.
div Return the result from dividing two numbers.
max Return the highest value from a set of numbers or an array.
min Return the lowest value from a set of numbers or an array.
mod Return the remainder from dividing two numbers.
mul Return the product from multiplying two numbers.
rand Return a random integer from a specified range.
range Return an integer array that starts from a specified integer.
sub Return the result from subtracting the second number from the first number.

Date and time functions

To work with dates and times, you can use these date and time functions. For the full reference about each function, see the alphabetical reference article.

Date or time function Task
addDays Add a number of days to a timestamp.
addHours Add a number of hours to a timestamp.
addMinutes Add a number of minutes to a timestamp.
addSeconds Add a number of seconds to a timestamp.
addToTime Add a number of time units to a timestamp. See also getFutureTime.
convertFromUtc Convert a timestamp from Universal Time Coordinated (UTC) to the target time zone.
convertTimeZone Convert a timestamp from the source time zone to the target time zone.
convertToUtc Convert a timestamp from the source time zone to Universal Time Coordinated (UTC).
dayOfMonth Return the day of the month component from a timestamp.
dayOfWeek Return the day of the week component from a timestamp.
dayOfYear Return the day of the year component from a timestamp.
formatDateTime Return the date from a timestamp.
getFutureTime Return the current timestamp plus the specified time units. See also addToTime.
getPastTime Return the current timestamp minus the specified time units. See also subtractFromTime.
startOfDay Return the start of the day for a timestamp.
startOfHour Return the start of the hour for a timestamp.
startOfMonth Return the start of the month for a timestamp.
subtractFromTime Subtract a number of time units from a timestamp. See also getPastTime.
ticks Return the ticks property value for a specified timestamp.
utcNow Return the current timestamp as a string.

Workflow functions

These workflow functions can help you:

  • Get details about a workflow instance at run time.
  • Work with the inputs used for instantiating logic apps.
  • Reference the outputs from triggers and actions.

For example, you can reference the outputs from one action and use that data in a later action. For the full reference about each function, see the alphabetical reference article.

Workflow function Task
action Return the current action's output at runtime, or values from other JSON name-and-value pairs. See also actions.
actionBody Return an action's body output at runtime. See also body.
actionOutputs Return an action's output at runtime. See actions.
actions Return an action's output at runtime, or values from other JSON name-and-value pairs. See also action.
body Return an action's body output at runtime. See also actionBody.
formDataMultiValues Create an array with the values that match a key name in form-data or form-encoded action outputs.
formDataValue Return a single value that matches a key name in an action's form-data or form-encoded output.
item When inside a repeating action over an array, return the current item in the array during the action's current iteration.
items When inside a for-each or do-until-loop, return the current item from the specified loop.
listCallbackUrl Return the "callback URL" that calls a trigger or action.
multipartBody Return the body for a specific part in an action's output that has multiple parts.
parameters Return the value for a parameter that is described in your logic app definition.
trigger Return a trigger's output at runtime, or from other JSON name-and-value pairs. See also triggerOutputs and triggerBody.
triggerBody Return a trigger's body output at runtime. See trigger.
triggerFormDataValue Return a single value matching a key name in form-data or form-encoded trigger outputs.
triggerMultipartBody Return the body for a specific part in a trigger's multipart output.
triggerFormDataMultiValues Create an array whose values match a key name in form-data or form-encoded trigger outputs.
triggerOutputs Return a trigger's output at runtime, or values from other JSON name-and-value pairs. See trigger.
variables Return the value for a specified variable.
workflow Return all the details about the workflow itself during run time.

URI parsing functions

To work with uniform resource identifiers (URIs) and get various property values for these URIs, you can use these URI parsing functions. For the full reference about each function, see the alphabetical reference article.

URI parsing function Task
uriHost Return the host value for a uniform resource identifier (URI).
uriPath Return the path value for a uniform resource identifier (URI).
uriPathAndQuery Return the path and query values for a uniform resource identifier (URI).
uriPort Return the port value for a uniform resource identifier (URI).
uriQuery Return the query value for a uniform resource identifier (URI).
uriScheme Return the scheme value for a uniform resource identifier (URI).

JSON and XML functions

To work with JSON objects and XML nodes, you can use these manipulation functions. For the full reference about each function, see the alphabetical reference article.

Manipulation function Task
addProperty Add a property and its value, or name-value pair, to a JSON object, and return the updated object.
coalesce Return the first non-null value from one or more parameters.
removeProperty Remove a property from a JSON object and return the updated object.
setProperty Set the value for a JSON object's property and return the updated object.
xpath Check XML for nodes or values that match an XPath (XML Path Language) expression, and return the matching nodes or values.

Next steps