---
title: "JSON Templating"
slug: "json-templating"
updated: 2025-09-15T09:43:05Z
published: 2025-09-15T09:43:05Z
canonical: "knowledge-base.rossum.ai/json-templating"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge-base.rossum.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# JSON Templating

JSON Templating engine is commonly used to configure many of our extensions.

## JSON Templating Syntax

The basic and most commonly used syntax is for getting values from the annotation object:

```json
{
  "some_field": "@{schema_id_of_datapoint}"
}
```

See also the `$DATAPOINT_VALUE$` section below for more verbose syntax.

## JSON Templating Operators

Operators are a special syntax that can be used to perform various complex operations when working with JSON.

### $DATAPOINT_MAPPING$

Returns rendered template specified in `mapping` for certain value of `schema_id`.

**Example**

```json
{
  "_ns_type": {
    "$DATAPOINT_MAPPING$": {
      "schema_id": "document_type",
      "mapping": {
        "tax_credit": "VendorCredit",
        "tax_invoice": "VendorBill"
      },
      "fallback_mapping": "Vendor" // optional
    }
  }
}
```

This template will return the following for `document_type` with value `tax_credit`:

```json
{ "_ns_type": "VendorCredit" }
```

Similarly, this template will return the following for `tax_invoice` value:

```json
{ "_ns_type": "VendorBill" }
```

Finally, the template will return the `_ns_type` of `Vendor` if no other value is found. This value can be omitted which will default to `null`.

**Available configuration options**

| Configuration option | Description | Required | Default |
| --- | --- | --- | --- |
| `schema_id` | Schema ID of the datapoint. | YES |  |
| `mapping` | Mapping of the datapoint value (schema_id). | YES |  |
| `fallback_mapping` | Default template that will be used if template for found datapoint value is not provided in the mapping. | NO | null |

### `$DATAPOINT_VALUE$`

`$DATAPOINT_VALUE$` is a more verbose syntax for `@{schema_id}`. In other words, the following examples are identical:

```json
{
  "externalId": "@{ns_external_id_generated}"
}
```

Identical to:

```json
{
  "externalId": {
    "$DATAPOINT_VALUE$": {
      "schema_id": "ns_external_id_generated",
      "value_type": "string"
    }
  }
}
```

While the latter might seem unnecessary, it is needed when we want to cast the value to a certain type. For example:

```json
{
  "tranDate": {
    "$DATAPOINT_VALUE$": {
      "schema_id": "date_issue",
      "value_type": "iso_datetime"
    }
  }
}
```

**Available configuration options**

| Configuration option | Description | Required | Default |
| --- | --- | --- | --- |
| `schema_id` | Schema ID of the datapoint. | YES |  |
| `value_type` | Type to which the value should be converted. Supported types are: `string`, `integer`, `float`, `boolean`, and `iso_datetime`. | NO | `string` |

### `$FOR_EACH_SCHEMA_ID$`

Iterates over multiline schema IDs, typically line items.

**Example**

```json
{
  "items": {
    "$FOR_EACH_SCHEMA_ID$": {
      "schema_id": "line_item",
      "mapping": {
        "_ns_type": "VendorBillItem",
        "quantity": "@{item_quantity}",
        "description": "@{item_description}"
      }
    }
  }
}
```

Will render:

```json
{
  "items": [
    {
      "_ns_type": "VendorBillItem",
      "quantity": "1",
      "description": "Some description 1"
    },
    {
      "_ns_type": "VendorBillItem",
      "quantity": "2",
      "description": "Some description 2"
    }
    // …
  ]
}
```

Inside the for-loop block, you can access a special variables (`schema_loop`):

- `schema_loop.index` for current iteration of the loop indexed from 1
- `schema_loop.index0` for current iteration of the loop indexed from 0

**Available configuration options**

| Configuration option | Description | Required | Default |
| --- | --- | --- | --- |
| `schema_id` | Schema ID of the datapoint. | YES |  |
| `mapping` | Mapping template that will be rendered for each element found with the given schema_id. | YES |  |
| `fallback_mapping` | Mapping template that will be rendered if no element with the given schema_id is found. | NO | `[]` |

### `$IF_DATAPOINT_VALUE$`

Renders the provided `mapping` template if the value of the given `schema_id` is equal to `value`. Otherwise, the whole parent key is skipped.

Note that if element with given `schema_id` is not found or multiple with the same `schema_id` is found an exception is raised.

**Example**

```json
{
  "Other_Field": 123,
  "Company_Reference": {
    "$IF_DATAPOINT_VALUE": {
      "schema_id": "company_match",
      "value": "my_company",
      "mapping": {
        "field_1": 456,
        "field_2": 789
      }
    }
  }
}
```

If `company_match` has value `my_company` the output will be:

```json
{
  "Other_Field": 123,
  "Company_Reference": {
    "field_1": 456,
    "field_2": 789
  }
}
```

If `company_match` has value that is different from `my_company` the output will be:

```json
{
  "Other_Field": 123
}
```

**Available configuration options**

| Configuration option | Description | Required | Default |
| --- | --- | --- | --- |
| `schema_id` | Schema ID of the relevant datapoint. | YES |  |
| `value` | Conditional (expected) value in `schema_id`. | YES |  |
| `fallback_mapping` | Mapping template that will be rendered if `schema_id` contains `value`. | YES |  |

### `$IF_SCHEMA_ID$`

Similar to `$FOR_EACH_SCHEMA_ID$` operation: it checks the existence of `schema_id`, and it either outputs `mapping` if the `schema_id` points to a non-empty value or `fallback_mapping` otherwise.

Note that if you don't specify the `fallback_mapping`, it will skip the whole parent key!

**Example**

```json
{
  "dueDate": {
    "$IF_SCHEMA_ID$": {
      "schema_id": "date_due",
      "mapping": {
        "$DATAPOINT_VALUE$": {
          "schema_id": "date_due",
          "value_type": "iso_datetime"
        }
      }
    }
  }
}
```

**Available configuration options**

| Configuration option | Description | Required | Default |
| --- | --- | --- | --- |
| `schema_id` | Schema ID of the datapoint. | YES |  |
| `mapping` | Mapping template that will be rendered if `schema_id` exists. | YES |  |
| `fallback_mapping` | Mapping template that will be rendered if no element with the given `schema_id` is found. Note that if you don't specify the `fallback_mapping`, it will skip the whole parent key! | NO |  |

> [!WARNING]
> 💬 YOUR FEEDBACK MATTERS!
> 
> Help us keep this page accurate and useful. Select **Yes** or **No** below, then use the feedback form to propose a correction, ask for clarification, or request a new article.