Folders
A folder in the knowledge base. Folders sit in a space, in another folder or in a document (parent_ref) and hold documents and more folders; a folder can also issue card keys through its key. Folders must not form a cycle. The import creates the folders under the spaces of the package, keeping sort_order among siblings: the spaces, folders and documents with the same parent. A folder without sort_order goes after the siblings that have one; siblings without it keep the order in which their files are listed in resource_files, and then the order of their records.
A record of this entity needs records of other entities in the package: Documents or Folders or Spaces.
Files in the package
List every file of this entity in resource_files of the manifest, with "resource": "folders". An entity can have any number of files. See Bundle format.
[
{
"resource": "folders",
"path": "resources/folders.json"
}
]Fields
| Field | Type | Required | Description |
|---|---|---|---|
external_id | string (ExternalId) | Yes | Your own identifier of the record, for example k-mrr, unique within the resource across all of its files and case sensitive. Other records refer to this one by it.Constraints: 1–512 characters. |
parent_ref | PolymorphicRef | Yes | Where the folder sits: an object with resource (spaces, folders or documents) and the external_id of that record.Constraints: resource is one of spaces, folders, documents. |
title | string | Yes | Name of the folder, for example Metrics Handbook.Constraints: 1–256 characters. |
author_ref | Ref<users>? refers to Users | No | The user who created the record, by the external_id of a users record, for example u-ava. Leave it out or use null when the author is unknown or has left. |
created_at | Timestamp | No | When the record was created, with a time zone, for example 2026-01-12T09:30:00Z.Constraints: RFC 3339 with a time zone. Default: |
description | RichText? | No | A short text about the folder, kept with it but not shown in the app; give the format with the text. Up to 1024 characters. Constraints: text up to 1024 characters. |
description.format | enum | Yes | A short text about the folder, kept with it but not shown in the app; give the format with the text. Up to 1024 characters. Constraints: one of plain_text, markdown, html. |
description.text | string | Yes | A short text about the folder, kept with it but not shown in the app; give the format with the text. Up to 1024 characters. Constraints: at most 1024 characters. |
key | string | No | The prefix of the card keys this folder issues, for example KPI_MRD_X7Q4: 2 to 16 characters, capital letters, digits and underscore, starting with a letter; a hyphen is not allowed. Leave it out when no card key comes from this folder. The card keys that use it are the key of cards, and the counter that numbers the next card of the folder continues after the highest number among them. A key is unique among spaces and folders together, and a key the target company already uses is replaced by a new one.Constraints: pattern ^[A-Z][A-Z0-9_]{1,15}$. |
sort_order | number | No | Position among the records next to it; a smaller number goes first and it must be greater than 0. Left out, the record goes to the end of the list. Constraints: > 0. Default: |
updated_at | Timestamp | No | When the folder was last changed, for example 2026-02-10T15:30:00Z. It is kept with the folder but not shown: the folder page shows only when and by whom the folder was created. Left out, it equals created_at.Constraints: RFC 3339 with a time zone. Default: |
References
Referenced by
- Documents:
parent_ref - Folders:
parent_ref - Spaces:
parent_ref - Tree entity roles:
tree_entity_ref
Folders
Show on the entity map
Example
A record of this entity:
{
"external_id": "f-handbook",
"parent_ref": {
"resource": "spaces",
"external_id": "s-kpi"
},
"title": "Metrics Handbook",
"description": {
"format": "markdown",
"text": "How Meridian defines, reviews and publishes its metrics."
},
"sort_order": 1,
"author_ref": "u-ava"
}Rules
- A key is unique among spaces and folders together.
- The value of key must be unique.
- parent_ref builds one tree together with Documents, Folders, Spaces; no record can be its own ancestor.
- A key must be unique within the company. Convertinator gives a key that the company already uses a new one and reports it before the import and on the final screen.
Related entities
Cards, Documents, Spaces
Check after the import
After the import, the records of this entity can be checked on Document groups › Retrieve document group.
JSON Schema
folders.json
