Entity Model
The Eidos schema -- the universal envelope structure for every entity in Arke.
The Eidos Schema
Every entity in Arke -- regardless of type -- is stored as an Eidos manifest. The schema defines the envelope; type profiles define what goes inside.
interface EidosV2 {
// Identity (immutable after creation)
schema: 'arke/eidos@v2';
id: string; // Entity ID (ULID)
type: string; // Entity type name
created_at: string; // ISO 8601 timestamp
// Versioning
ver: number; // Version number (starts at 1)
ts: string; // This version's timestamp
prev: { '/': string } | null; // Previous version CID (null for v1)
// Content
properties: Record<string, unknown>; // Metadata key-value pairs
relationships: Relationship[]; // Connections to other entities
components?: Record<string, { '/': string }>; // Large content stored separately
// Audit
edited_by: EditInfo; // Who made this version
note?: string; // Version description
}Version Links
The prev field uses the IPLD link convention { "/": "someCid" } to point to the previous version. This creates an immutable chain:
v3 (current tip)
└── prev → v2
└── prev → v1
└── prev → nullEvery version is stored by its content hash. You can traverse the full history of any entity by following prev links.
Relationships
Relationships connect entities to each other:
interface Relationship {
predicate: string; // e.g. "contains", "references", "parent"
peer: string; // Target entity ID
peer_type?: string; // Target's type hint
peer_label?: string; // Display name (denormalized)
properties?: Record<string, unknown>; // Relationship metadata
}Relationships are directional and stored as part of the entity manifest. Common predicates include contains (parent to child), parent (child to parent), and references (general link).
Edit Info
Every version records who made the change and how:
interface EditInfo {
user_id: string; // User or agent entity ID
method: 'manual' | 'ai_generated' | 'system' | 'import';
on_behalf_of?: string; // Original user if acting via agent
}Type Profiles
The base Eidos schema is intentionally minimal. Type-specific validation, required properties, and expected relationships are defined by profiles:
| Type | Profile | What it adds |
|---|---|---|
collection | arke/collection@v1 | Roles, membership, permission rules |
file | arke/file@v1 | MIME type, size, storage key, processing status |
folder | arke/folder@v1 | Hierarchical containment within collections |
user | arke/user@v1 | Display name, email, auth provider mapping |
agent | arke/agent@v1 | Endpoint URL, capabilities, API key binding |
group | arke/group@v1 | User/agent grouping for permissions |
chunk | arke/chunk@v1 | Text content, source reference, embedding status |
See the Schema Reference for full details on each profile.