---
source: https://carbone.io/documentation/design/advanced-features/key-value-mapping.html
title: "Translate values in JSON to human-readable text using a provided enum key-value map"
description: "Translate values in JSON to human-readable text using a provided enum key-value map"
generated_at: "2026-07-13"
---

# Key-value mapping

Translate values in JSON to human-readable text using a provided enum key-value map  
COMMUNITY FEATURE Available for:  
✓ Carbone Cloud  
✓ Carbone On-premise  
✓ Embedded Carbone JS   v2.0+ 

## :convEnum(type)

v0.13.0+

Convert user-defined enums to human readable values

User-defined enums must be passed in `options` of `carbone.render`.

| Params | Description | Type |
| --- | --- | --- |
| type | enum name passed in `options` of `carbone.render(data, options)` | String |

_Examples_

```javascript
// With API options: {
//   "enum": {
//     "ORDER_STATUS": [
//       "pending",
//       "sent",
//       "delivered"
//     ]
//   }
// }
{d.value:convEnum('ORDER_STATUS')} // input: 0 → output: "pending"
{d.value:convEnum('ORDER_STATUS')} // input: 1 → output: "sent"
{d.value:convEnum('ORDER_STATUS')} // input: 5 → output: 5
// With API options: {
//   "enum": {
//     "YES_NO": {
//       "true": "Yes",
//       "false": "No"
//     }
//   }
// }
{d.value:convEnum('YES_NO')} // input: false → output: "No"
{d.value:convEnum('YES_NO')} // input: true → output: "Yes"
{d.value:convEnum('YES_NO')} // input: null → output: null
{d.value:convEnum('UNKNOWN_ENUM')} // input: 3 → output: 3
```

## Related topics

- [Translations i18n](/documentation/design/advanced-features/translations-i18n.md)
- [Transform](/documentation/design/advanced-features/transform.md)
- [Digital signatures](/documentation/design/advanced-features/signatures.md)
- [Pictures](/documentation/design/advanced-features/pictures.md)
- [Pagination](/documentation/design/advanced-features/pagination.md)
- [Hyperlinks](/documentation/design/advanced-features/hyperlinks.md)