Folder

Reference for the arke/folder@v1 profile -- hierarchical containers within collections.

Profile

arke/folder@v1

Required Properties

Property	Type	Description
`label`	string	Display name (non-empty)

Optional Properties

Property	Type	Description
`description`	string	Short description
`rich_description`	string	Rich content description (markdown, Wikipedia-style)
`metadata`	object	Flexible metadata (author, title, date, etc.)

Relationships

Folder hierarchy uses bidirectional relationships:

Predicate	Peer Type	Direction	Description
`contains`	file, folder	Outward	Children this folder contains
`in`	folder, collection	Outward	Parent containers this folder is in
`collection`	collection	Outward	Owning collection (for permissions)

Hierarchy Model

Folders use contains/in bidirectional pairs:

Parent folder stores contains pointing to child
Child folder stores in pointing to parent

Both relationships are created/removed atomically by folder operations.

Example

A folder organizing chapters of Moby Dick:

{
  "schema": "arke/eidos@v1",
  "id": "01JCHAPTERS...",
  "type": "folder",
  "properties": {
    "label": "Chapters",
    "description": "All 135 chapters of Moby Dick",
    "metadata": {
      "chapter_count": 135
    }
  },
  "relationships": [
    { "predicate": "in", "peer": "01KFNR0H0Q791Y1SMZWEQ09FGV", "peer_type": "collection", "peer_label": "Moby Dick" },
    { "predicate": "collection", "peer": "01KFNR0H0Q791Y1SMZWEQ09FGV", "peer_type": "collection" },
    { "predicate": "contains", "peer": "01KFNR0Z394A878Y5AQ63MQEM2", "peer_type": "file", "peer_label": "chapter-001.txt" }
  ],
  "ver": 1,
  "created_at": "2025-01-15T10:00:00Z",
  "ts": 1736935200000,
  "edited_by": { "user_id": "01JUSER...", "method": "manual" }
}

Nesting

Folders can be nested to any depth. The hierarchy is maintained through bidirectional contains/in relationship pairs.

Both folders and collections can act as containers (parents). To create a folder hierarchy:

Create the folder via POST /entities with an in relationship pointing to the parent
Update the parent via PUT /entities/{id} with a contains relationship pointing to the new folder

See Folders for detailed hierarchy management patterns.

Validation Rules

Must have a non-empty label string
Parent (if specified via in relationship) must be a folder or collection

On this page