Type Profiles

Overview

Type profiles layer on top of the base Eidos schema. They define what goes inside the envelope:

Required and optional properties for this type
Typed TypeScript interfaces for the manifest
Expected relationships and predicates
Type-specific validation rules
Protected properties that require special endpoints

How Profiles Extend Eidos

Each profile defines a typed manifest interface that extends CurrentEidos:

// Example: Collection profile
export interface CollectionManifest extends CurrentEidos {
  type: 'collection';
  properties: CollectionProperties;
}

// Example: File profile
export interface FileManifest extends CurrentEidos {
  type: 'file';
  properties: FileProperties & Record<string, unknown>;
}

The CurrentEidos type automatically tracks the current schema version (currently arke/eidos@v1), so profiles adapt when the base schema evolves.

How Profiles Work

When an entity is created or updated:

Base Eidos validation runs first (envelope structure)
The entity's type field determines which profile applies
Profile-specific validation runs (required properties, relationship rules)
If the type is unknown, only base validation applies

Profile operations also:

Define typed input interfaces (CreateXxxInput, UpdateXxxInput)
Return typed result interfaces (XxxResult, UpdateXxxResult)
Provide type-specific operations (e.g., addRole for collections, uploadFileContent for files)

Some profiles define protected properties that cannot be modified via the generic PUT /entities/{id} endpoint. These properties have security implications and require type-specific endpoints with proper validation.

Entity Type	Protected Properties	Reason
`collection`	`roles`	Must use role management endpoints

Use the type-specific endpoints (e.g., role management endpoints) to modify protected properties.

Available Profiles

Profile	Type Constant	Description
Collection	`collection`	Permission container with roles and role assignments
File	`file`	Uploaded file with binary content in R2
Folder	`folder`	Hierarchical container with parent/child relationships
User	`user`	Human or service account identity

Profile Structure

Each profile in src/profiles/ typically includes:

File	Purpose
`types.ts`	Type constants, interfaces, input/result types
`index.ts`	Public exports
`operations.ts`	CRUD and type-specific operations
`validation.ts`	Validation functions (if complex validation needed)

Extensibility

You can create new entity types without modifying the base schema:

Define types: Create a manifest interface extending CurrentEidos with your type constant and properties interface
Create operations: Implement CRUD operations using the base entity operations
Register protected properties: Add to PROTECTED_PROPERTIES registry if needed
Export from profiles index: Add exports to src/profiles/index.ts

The base Eidos schema is open for properties, relationships, and types -- only the envelope structure is fixed.