---
source: https://carbone.io/documentation/design/formatters/overview.html
title: "How Carbone formatters works?"
description: "Translate raw data into human readable text."
generated_at: "2026-07-13"
---

# How formatters work

Translate raw data into human readable text.  
COMMUNITY FEATURE Available for:  
✓ Carbone Cloud  
✓ Carbone On-premise  
✓ Embedded Carbone JS   v2.0+ 

Formatters can be used to translate raw data into human readable text.

A formatter is applied to data using the separator `:`. Multiple formatters can be used one after another, each formatter input is the output of the previous one. Some formatters accept [constant](#constant-parameters) or [dynamic parameters](#dynamic-parameters).

Here is an example showing how to write `"John"` instead of `"JOHN"` using two chained formatters, and how to translate a raw ISO date into a human readable date.

```cdata
{
  "name"     : "JOHN",
  "birthday" : "2000-01-31"
}
```

```ctemplate
My name is {d.name:lowerCase:ucFirst}.
I was born on {d.birthday:formatD(LL)}.
```

```cresult
My name is John.
I was born on January 31, 2000.
```

## Constant parameters

Many formatters accept one or multiple parameters, separated by commas, enclosed in parentheses to modify the output.

For example, the formatter `:prepend(myPrefix)` adds the prefix "myPrefix."

> ⚠️ **Warning:** If your constant parameter contains a **comma** or **whitespace**, you must wrap the text with single quotes (straight quotes): `prepend('my prefix')`.

[Configure your text editor](/documentation/design/overview/design-best-practices.md#configuration-of-microsoft-word-and-libreoffice) to prevent quote replacement.

## Dynamic parameters

Formatters accept dynamic variables if parameters start with a `.` and are not surrounded by quotes.

Carbone accepts two methods:

-   with an **absolute JSON path**, starting with `d.` (root of the data object) or `c.` (root of the complement object) with some limitations
-   with a **relative JSON path** from the parent object, starting with a dot `.`

Here is the dataset used for the following examples:

```json
{
  "id" : 10,
  "qtyA" : 20,
  "subObject" : {
    "qtyB" : 5,
    "qtyC" : 3
  },
  "subArray" : [{
    "id" : 1000,
    "qtyE" : 3
  }]
}
```

Do a mathematical operation of `d.subObject.qtyB` + `d.subObject.qtyC`:

```js
{d.subObject.qtyB:add(d.subObject.qtyC)} // 8 (5 + 3)
```

Shorter alternative, with a relative JSON path:

```js
{d.subObject.qtyB:add(.qtyC)} // 8 (5 + 3)
```

Multiple dots can be used to access parent attributes with a relative JSON path:

```js
{d.subObject.qtyB:add(..qtyA):add(.qtyC)} // 28 (5 + 20 + 3)
```

Here is the same computation using an absolute JSON path:

```js
{d.subObject.qtyB:add(d.qtyA):add(d.subObject.qtyC)} // 28 (5 + 20 + 3)
```

Read parent objects and their children attributes (there is no limit in depth):

```js
{d.subArray[0].qtyE:add(..subObject.qtyC)} // 6 (3 + 3)
```

Access the first item of another table (only positive integers):

```js
{d.subObject.qtyB:add(..subArray[0].qtyE)} // 8 (5 + 3)
```

**Known limitations:**

Using custom iterators or array filters is **forbidden**:

```js
{d.subObject.qtyB:add(..subArray[i].qtyE)} 
{d.subObject.qtyB:add(..subArray[index, something=3].qtyE)} 
{d.subObject.qtyB:add(d.subArray[i].qtyE)} 
{d.subObject.qtyB:add(d.subArray[index].qtyE)} 
```

## Related topics

- [Text Formatting](/documentation/design/formatters/text.md)
- [Number Formatting](/documentation/design/formatters/number.md)
- [Interval and Duration](/documentation/design/formatters/interval.md)
- [Date Formatting](/documentation/design/formatters/date.md)
- [Currency Formatting](/documentation/design/formatters/currency.md)
- [Array manipulation](/documentation/design/formatters/array.md)