File

Reference for the arke/file@v1 profile -- entities optimized for file management.

Profile

arke/file@v1

Overview

The file type is optimized for managing uploaded files, but any entity type can have content attached. Content is stored in the properties.content map rather than as top-level properties.

Common Properties

Property	Type	Description
`label`	string	Display name for the file
`description`	string	User-provided description
`content`	ContentMap	Map of content keys to content entries

Content Map Structure

Content is stored as a map where keys identify different versions or derivatives:

interface ContentMap {
  [key: string]: ContentEntry;
}

interface ContentEntry {
  cid: string;           // Content identifier (hash of bytes)
  size: number;          // File size in bytes
  content_type: string;  // MIME type
  filename?: string;     // Original filename (for download headers)
  uploaded_at: string;   // ISO 8601 upload timestamp
}

Relationships

Predicate	Peer Type	Required	Description
`collection`	collection	Recommended	Owning collection (for permissions)
`in`	folder	No	Parent folder

Example

A file entity with content:

{
  "schema": "arke/eidos@v1",
  "id": "01KFNR0Z394A878Y5AQ63MQEM2",
  "type": "file",
  "properties": {
    "label": "Moby Dick (Full Text)",
    "description": "The complete novel by Herman Melville",
    "content": {
      "v1": {
        "cid": "bafkreigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
        "size": 1276201,
        "content_type": "text/plain",
        "filename": "moby-dick.txt",
        "uploaded_at": "2025-01-15T10:30:00Z"
      }
    }
  },
  "relationships": [
    { "predicate": "collection", "peer": "01KFNR0H0Q791Y1SMZWEQ09FGV", "peer_type": "collection" },
    { "predicate": "in", "peer": "01KFOLDER789...", "peer_type": "folder" }
  ],
  "ver": 1,
  "created_at": "2025-01-15T10:30:00Z",
  "ts": 1736937000000,
  "edited_by": { "user_id": "01JUSER...", "method": "manual" }
}

Multiple Content Versions

A single entity can have multiple content entries for different versions or derivatives:

{
  "properties": {
    "label": "Annual Report",
    "content": {
      "original": {
        "cid": "bafkrei_original...",
        "size": 2048576,
        "content_type": "application/pdf",
        "filename": "report-2024.pdf",
        "uploaded_at": "2025-01-15T10:30:00Z"
      },
      "thumbnail": {
        "cid": "bafkrei_thumb...",
        "size": 10240,
        "content_type": "image/png",
        "uploaded_at": "2025-01-15T10:31:00Z"
      },
      "v2": {
        "cid": "bafkrei_v2...",
        "size": 2150000,
        "content_type": "application/pdf",
        "filename": "report-2024-revised.pdf",
        "uploaded_at": "2025-01-20T14:00:00Z"
      }
    }
  }
}

Content Operations

Operation	Endpoint	Description
Upload	`POST /entities/{id}/content?key=v1`	Upload content with key
Download	`GET /entities/{id}/content?key=v1`	Download by key
Download by CID	`GET /entities/{id}/content?cid=bafkrei...`	Download by CID
Rename	`PATCH /entities/{id}/content`	Rename content key
Delete	`DELETE /entities/{id}/content?key=v1`	Remove content entry

See Files & Content for complete upload and download workflows.

On this page