> ## Documentation Index
> Fetch the complete documentation index at: https://tyk.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Go Templates

> How to configure Go Templates traffic transformation middleware in Tyk

Tyk's [request](/5.8/api-management/traffic-transformation/request-body) and [response](/5.8/api-management/traffic-transformation/response-body) body transform middleware use the [Go template language](https://golang.org/pkg/text/template/) to parse and modify the provided input.

Go templates are also used by Tyk's [webhook event handler](/5.8/api-management/gateway-events#event-handling-with-webhooks) to produce the payload for the HTTP request sent to the target system.

In this section of the documentation, we provide some guidance and a few examples on the use of Go templating with Tyk.

## Data format conversion using helper functions

Tyk provides two helper functions to assist with data format translation between JSON and XML:

* `jsonMarshal` performs JSON style character escaping on an XML field and, for complex objects, serialises them to a JSON string ([example](/5.8/#xml-to-json-conversion-using-jsonmarshal))
* `xmlMarshal` performs the equivalent conversion from JSON to XML ([example](/5.8/#json-to-xml-conversion-using-xmlmarshal))

When creating these functions within your Go templates, please note:

* the use of `.` in the template refers to the entire input, whereas something like `.myField` refers to just the `myField` field of the input
* the pipe `|` joins together the things either side of it, which is typically input data on the left and a receiving command to process the data on the right, such as `jsonMarshal`

Hence `{{ . | jsonMarshal }}` will pass the entire input to the `jsonMarshal` helper function.

## Using functions within Go templates

You can define and use functions in the Go templates that are used for body transforms in Tyk. Functions allow you to abstract common template logic for cleaner code and to aid reusability. Breaking the template into functions improves readability of more complex tenplates.

Here is an example where we define a function called `myFunction` that accepts one parameter:

```go theme={null}
{{- define "myFunction" }}
  Hello {{.}}!
{{- end}}
```

We can call that function and pass "world" as the parameter:

```go theme={null}
{
  "message": {{ call . "myFunction" "world"}}
}
```

The output would be:

```json theme={null}
{
  "message": "Hello world!" 
}
```

We have bundled the [Sprig Library (v3)](http://masterminds.github.io/sprig/) which provides over 70 pre-written functions for transformations to assist the creation of powerful Go templates to transform your API requests.

## Additional resources

Here's a useful [blog post](https://blog.gopheracademy.com/advent-2017/using-go-templates/) and [YouTube tutorial](https://www.youtube.com/watch?v=k5wJv4XO7a0) that can help you to learn about using Go templates.

## Go templating examples

Here we provide worked examples for both [JSON](/5.8/#example-json-transformation-template) and [XML](/5.8/#example-xml-transformation-template) formatted inputs. We also explain examples using the [jsonMarshal](/5.8/#xml-to-json-conversion-using-jsonmarshal) and [xmlMarshal](/5.8/#json-to-xml-conversion-using-xmlmarshal) helper functions.

### Example JSON transformation template

Imagine you have a published API that accepts the request listed below, but your upstream service requires a few alterations, namely:

* swapping the values of parameters `value1` and `value2`
* renaming the `value_list` to `transformed_list`
* adding a `user-id` extracted from the session metadata
* adding a `client-ip` logging the client IP
* adding a `req-type` that logs the value provided in query parameter `type`

**Input**

* Session metadata `uid` = `user123`
* IP address of calling client = `192.0.0.1`
* Query parameter `type` = `strict`

```json theme={null}
{
  "value1": "value-1",
  "value2": "value-2",
  "value_list": [
    "one",
    "two",
    "three"
  ]
}
```

**Template**

```go theme={null}
{
  "value1": "{{.value2}}",
  "value2": "{{.value1}}",
  "transformed_list": [
    {{range $index, $element := index . "value_list"}}
    {{if $index}}, {{end}}
    "{{$element}}"
    {{end}}
  ],
  "user-id": "{{._tyk_meta.uid}}",
  "user-ip": "{{._tyk_context.remote_addr}}",
  "req-type": "{{ ._tyk_context.request_data.param.type }}" 
}
```

In this template:

* `.value1` accesses the "value1" field of the input JSON
* we swap value1 and value2
* we use the range function to loop through the "value\_list" array
* `._tyk_meta.uid` injects the "uid" session metadata value
* `._tyk_context.remote_addr` injects the client IP address from the context
* `._tyk_context.request_data.param.type` injects query parameter "type"

**Output**

```.json theme={null}
{
  "value1": "value-2",
  "value2": "value-1",
  "transformed_list": [
    "one",
    "two",
    "three"
  ],
  "user-id": "user123"
  "user-ip": "192.0.0.1"
  "req-type": "strict"
}
```

### Example XML transformation template

XML cannot be as easily decoded into strict structures as JSON, so the syntax is a little different when working with an XML document. Here we are performing the reverse translation, starting with XML and converting to JSON.

**Input**

* Session metadata `uid` = `user123`
* IP address of calling client = `192.0.0.1`
* Query parameter `type` = `strict`

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<data>
  <body>
    <value1>value-1</value1>
    <value2>value-2</value2>
    <valueList>
      <item>one</item>
      <item>two</item>
      <item>three</item>
    </valueList>
  </body>
</data>
```

**Template**

```.xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<data>
  <body>
    <value1>{{ .data.body.value2 }}</value1>
    <value2>{{ .data.body.value1 }}</value2>
    <transformedList>
      {{range $index, $element := .data.body.valueList.item }}
      <item>{{$element}}</item>
      {{end}}
    </transformedList>
    <userId>{{ ._tyk_meta.uid }}</userId>
    <userIp>{{ ._tyk_context.remote_addr }}</userIp>
    <reqType>{{ ._tyk_context.request_data.param.type }}</reqType>
  </body>
</data>
```

In this template:

* `.data.body.value1` accesses the "value1" field of the input XML
* we swap value1 and value2
* we use the range function to loop through the "value\_list" array
* `._tyk_meta.uid` injects the "uid" session metadata value
* `._tyk_context.remote_addr` injects the client IP address from the context
* `._tyk_context.request_data.param.type` injects query parameter "type"

**Output**

```.xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<data>
  <body>
    <value1>value-2</value1>
    <value2>value-1</value2>
    <transformedList>
      <item>one</item>
      <item>two</item>
      <item>three</item>
    </transformedList>
    <userId>user123</userId>
    <userIp>192.0.0.1</userIp>
    <reqType>strict</reqType>
  </body>
</data>
```

### XML to JSON conversion using jsonMarshal

The `jsonMarshal` function converts XML formatted input into JSON, for example:

**Input**

```xml theme={null}
<hello>world</hello>
```

**Template**

```go theme={null}
{{ . | jsonMarshal }}
```

**Output**

```json theme={null}
{"hello":"world"}
```

Note that in this example, Go will step through the entire data structure provided to the template. When used in the [Request](/5.8/api-management/traffic-transformation/request-body#data-accessible-to-the-middleware) or [Response](/5.8/api-management/traffic-transformation/request-body#data-accessible-to-the-middleware) Body Transform middleware, this would include Context Variables and Session Metadata if provided to the middleware.

### JSON to XML conversion using xmlMarshal

The `xmlMarshal` function converts JSON formatted input into XML, for example:

**Input**

```json theme={null}
{"hello":"world"}
```

**Template**

```.go theme={null}
{{ . | xmlMarshal }}
```

**Output**

```xml theme={null}
<hello>world</hello>
```

Note that in this example, Go will step through the entire data structure provided to the template. When used in the [Request](/5.8/api-management/traffic-transformation/request-body#data-accessible-to-the-middleware) or [Response](/5.8/api-management/traffic-transformation/request-body#data-accessible-to-the-middleware) Body Transform middleware, this would include Context Variables and Session Metadata if provided to the middleware.