# CSV Template Structure (Add new items)

## 1. Purpose

This document provides formal guidance on the required CSV structure for adding new metadata objects to Decube using the Export/Import feature. It is intended for data stewards and administrators responsible for bulk onboarding of metadata. The document details supported object types, required and optional fields, field-level constraints, and provides examples to ensure accurate template completion.

## 2. Supported Object Types

The "Add New Items" workflow supports the creation of the following object types:

* Glossary Objects: Glossary, Category, and Term (within a single template)
* Classification Policies

To begin, download the appropriate CSV templates from the platform at **Export/Import > Export > Add New Items**.

## 3. Important Requirements

Follow these requirements for a successful import:

* **Use only official templates:** Download templates from [docs.decube.io](https://docs.decube.io/export-for-creating-new-objects#csv-templates) to avoid schema mismatch errors.
* **Do not rename headers:** Modifying column headers will result in import failure.
* **Specify correct `Type` values:** The `Type` field must be set to one of: Glossary, Category, or Term, as appropriate.
* **Multi-value fields:** For fields such as Tags, Owners, Related Terms, and Linked Assets, use comma-separated values.
* **Single object type per file:** Each file should contain only one logical operation (e.g., all glossary rows or all policy rows).
* **Complete all required fields:** All required fields must be filled. Optional fields may be left empty.
* **Field limits:**
  * Description: Maximum 8,000 characters
  * Tags/Owners: Maximum 3 entries
  * Names: Maximum 100 characters
  * Policy\_tag: Must not contain space or special characters
* **Formatting for Linked Assets and Related Terms:**
  * Linked Assets: `type:source.schema.table.column`
  * Related Terms: `Glossary.Category.Term`
* **Empty attributes:** Empty values in editable fields will overwrite and clear existing values. These will not trigger errors but will be treated as intentional.
* **Custom attributes on new Glossary/Category/Term:** You may include custom attribute columns using `CA: <Attribute Name>` to set values on newly created glossary items. The same rules apply as for editing: enum supports multi-select via commas (escape commas in option labels with `\,`), and User attributes must contain registered user emails (up to 20 emails per cell). Leaving a `CA:` cell empty simply omits the value.
* Custom Attributes must be created in your organization's settings before they can be referenced in export/import CSVs. See [Creating & managing custom attributes](https://docs.decube.io/org-settings/custom-attributes).

Below is a breakdown of editable fields, format requirements, character limits, and constraints by object type.

{% hint style="info" %}
All empty value in any editable attribute will overwrite and clear the existing value.
{% endhint %}

## 4. Glossary, Category, and Term Objects

All three object types—Glossary, Category, and Term—are managed within a single CSV file. The value specified in the `Type` field determines the object being created in each row. The requirements for other fields are conditional based on the selected type.

> **Note:** When a glossary object name contains a period (`.`), precede the period with a backslash (e.g., `Marketing.Plans` should be entered as `marketing\.plans`).

**Field Requirements:**

* Set the `Type` field to one of: Glossary, Category, or Term.
* When adding a Term under a Category, both the Glossary and Category fields are required.
* A Term may also be added directly under a Glossary (without a Category).
* Leave identifier fields blank if they are not applicable for the selected type.

### Template Fields for Glossary, Category, and Term

| Field           | Field Type         | Required    | Description                               | Constraints                                                              | Example             |
| --------------- | ------------------ | ----------- | ----------------------------------------- | ------------------------------------------------------------------------ | ------------------- |
| Glossary        | Identifier         | Yes         | Name of the glossary                      | Max 100 characters, unique                                               | Glossary\_1         |
| Category        | Identifier         | Conditional | Name of the category (see notes above)    | Max 100 characters, unique                                               | -                   |
| Term            | Identifier         | Conditional | Name of the term (see notes above)        | Max 100 characters, unique                                               | -                   |
| Type            | Identifier         | Yes         | Object type (Glossary, Category, or Term) | Must be one of the supported types                                       | Glossary            |
| Data Owners     | Editable Attribute | No          | Designated data owners                    | Comma-separated emails, max 3; must be registered users in Decube        | <user@org.com>      |
| Business Owners | Editable Attribute | No          | Designated business owners                | Comma-separated emails; must be registered users in Decube               | <user@org.com>      |
| Description     | Editable Attribute | Yes         | Description for the object                | Max 8,000 characters                                                     | Some text           |
| Classifications | Editable Attribute | No          | Policy tags (only for Term)               | Must match existing policy, must not contain space or special characters | PII                 |
| Related Terms   | Editable Attribute | No          | Related terms (only for Term)             | Format: glossary.term, comma-separated                                   | Glossary\_1.Term\_1 |

### Example: Valid CSV Input for Glossary, Category, and Term

Below is an example of a valid CSV input for adding new Glossary, Category, and Term objects. Each row represents a single object, and the `Type` field determines the object type.

{% hint style="info" %}
Note: While trying the examples below, ensure that:

* The users listed under Data Owners and Business Owners fields must be active users on the platform.
* The related terms referenced must already exist on the platform.
  {% endhint %}

| Glossary | Category | Term   | Type     | Data Owners     | Business Owners | Description               | Classifications | Related Terms       |
| -------- | -------- | ------ | -------- | --------------- | --------------- | ------------------------- | --------------- | ------------------- |
| Finance  |          |        | Glossary | <alice@org.com> | <bob@org.com>   | Finance glossary          |                 |                     |
| Finance  | Revenue  |        | Category | <alice@org.com> |                 | Revenue category          |                 |                     |
| Finance  | Revenue  | ARR    | Term     | <alice@org.com> |                 | Annual Recurring Revenue  | PII             |                     |
| Finance  | Revenue  | MRR    | Term     |                 |                 | Monthly Recurring Revenue |                 | Finance.Revenue.ARR |
| Finance  |          | EBITDA | Term     |                 |                 | Earnings Before Interest  |                 |                     |

> **Note:** Leave fields blank if not applicable for the object type in that row. Ensure all required fields are completed as per the table above.

## 5. Classification Policies

To create new classification policies, use the official template available at [Export/Import > Export > Add New Items](https://docs.decube.io/export-for-creating-new-objects#download-classification-policy-csv-template).

### Template Fields for Classification Policies

| Field       | Field Type         | Required | Description                       | Constraints                                                            | Example            |
| ----------- | ------------------ | -------- | --------------------------------- | ---------------------------------------------------------------------- | ------------------ |
| Name        | Identifier         | Yes      | Name of the classification policy | Unique                                                                 | PII Classification |
| Policy Tag  | Identifier         | Yes      | Short unique tag for the policy   | Max 5 characters, unique, must not contain space or special characters | PII                |
| Description | Editable Attribute | No       | Description of the policy         | -                                                                      | Protects PII data  |
| Purpose     | Editable Attribute | No       | Purpose of the policy             | -                                                                      | Regulatory         |
| Stewards    | Editable Attribute | No       | Responsible users                 | Comma-separated emails; must be registered users in Decube             | <user@org.com>     |

### Example: Valid CSV Input for Classification Policies

Below is an example of a valid CSV input for adding new classification policies. Each row represents a single policy.

| Name                | Policy Tag | Description       | Purpose    | Stewards                      |
| ------------------- | ---------- | ----------------- | ---------- | ----------------------------- |
| PII Classification  | PII        | Protects PII data | Regulatory | <alice@org.com>               |
| GDPR Policy         | GDPR       | GDPR compliance   | Compliance | <bob@org.com>                 |
| Confidential Policy | CONF       | Internal only     | Internal   | <alice@org.com>,<bob@org.com> |

> **Note:** The Stewards field must contain only users registered within the Decube platform. Ensure all required fields are completed as per the table above.

### Example: Adding custom attributes to new glossary items

You can set custom attributes during creation by adding `CA:` columns. Example header and row:

```
Glossary, Category, Term, Type, Description, CA: Data Sensitivity, CA: Domain Owner, CA: Compliance Tags
Finance, Revenue, MRR, Term, Monthly Recurring Revenue, Confidential, alice@org.com,bob@org.com, Finance\,Core,Legal
```

These requirements ensure consistent structure and validation for adding metadata in bulk via CSV Export/Import. Verify that all identifier fields are correct and that each row adheres to the specified constraints to avoid import failures.