Carbone

View saved version →

---
name: carbone
description: >
  Carbone templating: merge JSON data into a DOCX (Word), XLSX (Excel), PPTX (PowerPoint), ODT, ODS,
  HTML, Markdown or PDF template, plus text/XML formats such as CSV, TXT, SVG and IDML. Use this skill
  to design, validate, fix or explain Carbone syntax: tags, loops, conditions, formatters, aggregators,
  aliases, and mapping a JSON dataset onto a template. Trigger on: the tag syntax {d.} {c.} {#alias}
  {$alias} {t()} {o.} or any :formatter chain; a template error such as a missing [i+1]; whether a
  format supports a feature or what it converts to; filling a PDF form (AcroForm); adding a chart,
  barcode or dynamic image to a document; writing a number or an amount in words; dynamic Excel
  formulas; upgrading between Carbone versions;
  and any request to build an invoice, contract or report from JSON, mail-merge data into a document,
  fill a template with data, or convert a document (HTML or Markdown to PDF, DOCX to PDF).
license: Apache-2.0
metadata:
  author: carboneio
  version: "2.1.0"
  carbone_version: "5.17.0"
  repository: https://github.com/carboneio/carbone-agent-plugin
---

# Carbone Universal Templating Language — Skill

Carbone is a **declarative** templating engine. You provide a template (DOCX, XLSX, PPTX, ODT, HTML, …) with **Carbone tags** (placeholders in `{}`), plus a JSON dataset. Carbone merges both to produce the filled document.

> **NEVER invent Carbone syntax.**
> Carbone is its own language — it is NOT JSONPath, NOT Mustache, NOT Handlebars, NOT Jinja2, NOT any other templating language. Its tag syntax, formatters, loop markers, and filter expressions are unique. Any pattern not explicitly documented in this skill or its reference files does not exist in Carbone. If a user's request cannot be answered from what is documented here, say so — do not guess or adapt syntax from another language.

**Design principles — they change how you answer:**
- **Adapt the template to the data, never the data to the template.** Carbone injects into an unmodified API response. Reach for array filters, sorting, lookups and `:set` before suggesting the user reshape their JSON.
- **Format-agnostic.** Carbone injects into the file's own markup — the XML inside DOCX/ODT/IDML and any other XML-based format, and text files such as TXT, CSV, Markdown or JSON (§9).
- **Backward compatible.** Tag syntax survives upgrades — a template written for v2 still renders on v12. Never warn a user that their existing tags will break in a newer version.

---

## 1. Tag Types and Prefixes

| Tag | Purpose |
|---|---|
| `{d.path}` | Data from the main JSON object (most common) |
| `{c.path}` | Data from the "complement" object (metadata / computed values) |
| `{c.now}` | Built-in: current date/time at render time (UTC). Chain with `:formatD` to display it. |
| `{#alias = d.path}` | Declare an alias shortcut (removed from output) |
| `{$alias}` | Use a declared alias |
| `{t(key)}` | Static i18n translation tag — no quotes needed, whitespace preserved |
| `{o.option=value}` | Carbone in-template option (removed from output) |

### Special `{o.}` options
Common: `{o.timezone=Europe/Paris}` `{o.lang=en-US}` `{o.converter=L}` `{o.useHighPrecisionArithmetic=true}` `{o.exportFormattedValuesAsText=true}` (XLSX only) `{o.hardRefresh=true}` (force converter even when input/output format match — useful for XLSX formula refresh) `{o.preReleaseFeatureIn=VERSION}` (opt-in pre-release features).
Full in-template option list → `references/in-template-options.md`.

---

## 2. Basic Placeholders

| Goal | Tag |
|---|---|
| Simple property | `{d.firstname}` |
| Nested property | `{d.user.address.city}` |
| Array item by position | `{d.items[0].name}` or `{d.items[i=0].name}` |
| Last array item | `{d.items[i=-1].name}` |
| Second to last | `{d.items[i=-2].name}` |
| Parent object property | `{d.child..parentProp}` (`..` = up 1 level, `...` = up 2 levels) |

### Array search (without loop)
Search the first matching item

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 15 — file references are metadata, not package contents.