Using Liquid Markup in YAML

This use case describes the recommended syntax (the use of ', ", >, |, and indentation) when using Liquid markup in YAML in platformOS.

Requirements

To follow this use case, you should be familiar with basic platformOS concepts, and the topics in the Get Started section. You should also know how Liquid markup and YAML are used in platformOS:

• Liquid markup is a template language used in platformOS to build dynamic pages, and to provide dynamic configuration (e.g. based on currently logged in user). We have added platformOS-specific filters and tags — visit our Complete Guide to Liquid Markup to learn more.
• YAML is a human-friendly data serialization standard used in platformOS for setting properties in configuration files. To learn more, visit the Official YAML Documentation.
• Get Started

Using Liquid markup in YAML

We demonstrate our recommendations on this example:

---
to: 'https://example.com/endpoint/{{ form.id }}'
format: http
callback: >
  {% log response, type: 'response object' %}
  {% assign response_hash = response.body | parse_json %}
  {% log response_hash, type: 'response body as hash' %}
request_type: POST
request_headers: '{
  "Content-Type": "application/json"
}'
---
{
  "first_name": "{{ form.first_name }}",
  "id": "{{ form.id }}"
}

Take a look at each of these keys and how values are formatted:

1. The to value is using ' to wrap the string, you could use " as well.
2. format and request_type are not using any quotes since they are optional with single line values unless you have some special characters inside.
3. request_headers uses a ' to wrap the string inside, and this is the only valid quote format, since the string itself uses ". Notice, that the third line is not indented. You could alternatively use backslashes inside to escape the " like so:

request_headers: "{
  \"Content-Type\": \"application/json\"
}"

and then you are free to use ". Quotes are needed since this is a multiline string.

4. callback uses yet another syntax for multiline content. When you use > you need to indent the content with two spaces but you don’t have to escape any characters inside and do not have to wrap the value in quotes. Alternatively, you could use | instead of > as it differs only with how new lines are treated.

Conclusion

Take a look at the example code:

headers: |-
{%- assign token = context.constants.api_user_name | append: ":" | append: context.constants.api_user_password -%}
'{
  "Content-Type": "application/json",
  "Authorization": "Basic {{ token | base64_encode }}"
}'
---

You may notice two different approaches mixed here. I the example, the developer used | - (yet another alternative, stripping whitespace around the value) but did not indent the code. You also added quotes around JSON, but in this case, it would include them as part of the value and result in invalid JSON. The example could be written as:

headers: |-
  {%- assign token = context.constants.api_user_name | append: ":" | append: context.constants.api_user_password -%}
  {
    "Content-Type": "application/json",
    "Authorization": "Basic {{ token | base64_encode }}"
  }

or

headers: '{%- assign token = context.constants.api_user_name | append: ":" | append: context.constants.api_user_password -%}
{
  "Content-Type": "application/json",
  "Authorization": "Basic {{ token | base64_encode }}"
}'

We recommend the first approach as you don’t have to think about escaping any characters inside.