{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "imports-v2/folders.json",
  "title": "Folders",
  "description": "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.",
  "type": "object",
  "properties": {
    "external_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "description": "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."
    },
    "parent_ref": {
      "type": "object",
      "properties": {
        "resource": {
          "type": "string",
          "enum": [
            "spaces",
            "folders",
            "documents"
          ]
        },
        "external_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 512
        }
      },
      "required": [
        "resource",
        "external_id"
      ],
      "additionalProperties": false,
      "x-refs": [
        "spaces",
        "folders",
        "documents"
      ],
      "description": "Where the folder sits: an object with `resource` (`spaces`, `folders` or `documents`) and the `external_id` of that record."
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256,
      "description": "Name of the folder, for example `Metrics Handbook`."
    },
    "description": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "format": {
          "type": "string",
          "enum": [
            "plain_text",
            "markdown",
            "html"
          ]
        },
        "text": {
          "type": "string",
          "maxLength": 1024
        }
      },
      "required": [
        "format",
        "text"
      ],
      "additionalProperties": false,
      "x-link-tokens": [
        {
          "scheme": "attachment",
          "resource": "attachments"
        },
        {
          "scheme": "card",
          "resource": "cards"
        },
        {
          "scheme": "document",
          "resource": "documents"
        }
      ],
      "description": "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."
    },
    "key": {
      "type": "string",
      "pattern": "^[A-Z][A-Z0-9_]{1,15}$",
      "description": "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."
    },
    "sort_order": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "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.",
      "x-default-text": "the end of the list"
    },
    "author_ref": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 512,
      "x-ref": "users",
      "description": "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": {
      "type": "string",
      "format": "date-time",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$",
      "description": "When the record was created, with a time zone, for example `2026-01-12T09:30:00Z`.",
      "x-default-text": "source.exported_at of the manifest"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$",
      "description": "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`.",
      "x-default-text": "created_at"
    }
  },
  "required": [
    "external_id",
    "parent_ref",
    "title"
  ],
  "additionalProperties": false
}