Eidos Schema

Schema Identifier

arke/eidos@v1

Interface

interface EidosV1 {
  schema: 'arke/eidos@v1';
  id: string;
  type: string;
  created_at: string;

  ver: number;
  ts: number;
  prev: { '/': string } | null;

  properties: Record<string, unknown>;
  relationships: Relationship[];

  edited_by: EditInfo;
  note?: string;
}

Required Fields

Field	Type	Constraint
`schema`	string	Must be `arke/eidos@v1`
`id`	string	Valid entity ID (see ID format below)
`type`	string	Non-empty
`created_at`	string	ISO 8601 datetime
`ver`	number	Positive integer (>= 1)
`ts`	number	Unix timestamp in milliseconds
`prev`	IPLDLink or null	null iff ver=1
`properties`	object	At minimum `{}`
`relationships`	array	At minimum `[]`
`edited_by`	EditInfo	Valid structure

Optional Fields

Field	Type	Description
`note`	string	Version note describing the change

Entity ID Format

Entity IDs follow specific formats depending on the network and entity type:

Network/Type	Format	Example
Main network	26-char ULID (Crockford Base32)	`01JDEF6W2PKTV9M7P3AB4CDEF1`
Test network	`II` prefix + 24 chars	`II0DEF6W2PKTV9M7P3AB4CDE`
File entities	`F` prefix + 25 chars (deterministic)	`F0DEF6W2PKTV9M7P3AB4CDEF1`
Chunk entities	`C` prefix + 25 chars (deterministic)	`C0DEF6W2PKTV9M7P3AB4CDEF1`

The ID format uses Crockford Base32 characters: 0-9A-HJKMNP-TV-Z (excludes I, L, O, U to avoid ambiguity).

Relationship Structure

interface Relationship {
  predicate: string;
  peer: string;
  peer_type?: string;
  peer_label?: string;
  properties?: Record<string, unknown>;
}

Field	Required	Description
`predicate`	Yes	Relationship type (e.g., `parent`, `contains`, `owner`)
`peer`	Yes	Target entity ID or `*` for wildcard (used in permissions)
`peer_type`	No	Type hint for the peer entity
`peer_label`	No	Display label for the peer (populated during expansion)
`properties`	No	Additional metadata for the relationship

Relationships are stored on the "from" side. For example, if entity A has a parent relationship to entity B, the relationship is stored on A.

EditInfo Structure

interface EditInfo {
  user_id: string;
  user_label?: string;
  method: 'manual' | 'ai_generated' | 'system' | 'import';
  on_behalf_of?: string;
  on_behalf_of_label?: string;
}

Field	Required	Description
`user_id`	Yes	ID of the user or agent making the edit
`user_label`	No	Display name (populated during expansion with `?expand=relationships`)
`method`	Yes	How the edit was made
`on_behalf_of`	No	ID of the user the edit is being made for (agent delegation)
`on_behalf_of_label`	No	Display name (populated during expansion)

Edit Methods

Method	Description
`manual`	User-initiated edit through the UI or API
`ai_generated`	Content created or modified by an AI agent
`system`	System-level operation (migrations, automated processes)
`import`	Bulk import from external source

IPLDLink Format

Version chain links use the IPLD convention for content-addressed links:

interface IPLDLink {
  '/': string;  // CID (Content Identifier)
}

Example: { "/": "bafkreihdwdcefgh4dqkjv67uzcmw7ojee6xedzdetojuzjevtenxquvyku" }

While the naming references IPLD (InterPlanetary Linked Data), actual storage is on Cloudflare R2/D1. CIDs are computed locally using the same algorithm for content-addressing guarantees.

Validation Rules

schema must be arke/eidos@v1
All required fields must be present
ver === 1 requires prev === null
ver > 1 requires prev !== null
edited_by must have valid user_id (non-empty) and method
relationships must be an array of valid Relationship objects
properties must be an object
id must match the entity ID format regex
created_at must be a valid ISO 8601 datetime string
ts must be a positive integer (Unix timestamp in milliseconds)

The base schema does not validate what's inside properties or which relationships exist -- that's delegated to type-specific profiles.

On this page